Expressions
Every AST node in SQLGlot is represented by a subclass of Expression.
This module contains the implementation of all supported Expression types. Additionally,
it exposes a number of helper functions, which are mainly used to programmatically build
SQL expressions, such as sqlglot.expressions.select.
1""" 2## Expressions 3 4Every AST node in SQLGlot is represented by a subclass of `Expression`. 5 6This module contains the implementation of all supported `Expression` types. Additionally, 7it exposes a number of helper functions, which are mainly used to programmatically build 8SQL expressions, such as `sqlglot.expressions.select`. 9 10---- 11""" 12 13from __future__ import annotations 14 15import datetime 16import math 17import numbers 18import re 19import typing as t 20from collections import deque 21from copy import deepcopy 22from enum import auto 23 24from sqlglot.errors import ParseError 25from sqlglot.helper import ( 26 AutoName, 27 camel_to_snake_case, 28 ensure_collection, 29 seq_get, 30 split_num_words, 31 subclasses, 32) 33from sqlglot.tokens import Token 34 35if t.TYPE_CHECKING: 36 from sqlglot.dialects.dialect import DialectType 37 38 39class _Expression(type): 40 def __new__(cls, clsname, bases, attrs): 41 klass = super().__new__(cls, clsname, bases, attrs) 42 43 # When an Expression class is created, its key is automatically set to be 44 # the lowercase version of the class' name. 45 klass.key = clsname.lower() 46 47 # This is so that docstrings are not inherited in pdoc 48 klass.__doc__ = klass.__doc__ or "" 49 50 return klass 51 52 53class Expression(metaclass=_Expression): 54 """ 55 The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary 56 context, such as its child expressions, their names (arg keys), and whether a given child expression 57 is optional or not. 58 59 Attributes: 60 key: a unique key for each class in the Expression hierarchy. This is useful for hashing 61 and representing expressions as strings. 62 arg_types: determines what arguments (child nodes) are supported by an expression. It 63 maps arg keys to booleans that indicate whether the corresponding args are optional. 64 65 Example: 66 >>> class Foo(Expression): 67 ... arg_types = {"this": True, "expression": False} 68 69 The above definition informs us that Foo is an Expression that requires an argument called 70 "this" and may also optionally receive an argument called "expression". 71 72 Args: 73 args: a mapping used for retrieving the arguments of an expression, given their arg keys. 74 parent: a reference to the parent expression (or None, in case of root expressions). 75 arg_key: the arg key an expression is associated with, i.e. the name its parent expression 76 uses to refer to it. 77 comments: a list of comments that are associated with a given expression. This is used in 78 order to preserve comments when transpiling SQL code. 79 _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the 80 optimizer, in order to enable some transformations that require type information. 81 """ 82 83 key = "expression" 84 arg_types = {"this": True} 85 __slots__ = ("args", "parent", "arg_key", "comments", "_type") 86 87 def __init__(self, **args: t.Any): 88 self.args: t.Dict[str, t.Any] = args 89 self.parent: t.Optional[Expression] = None 90 self.arg_key: t.Optional[str] = None 91 self.comments: t.Optional[t.List[str]] = None 92 self._type: t.Optional[DataType] = None 93 94 for arg_key, value in self.args.items(): 95 self._set_parent(arg_key, value) 96 97 def __eq__(self, other) -> bool: 98 return type(self) is type(other) and _norm_args(self) == _norm_args(other) 99 100 def __hash__(self) -> int: 101 return hash( 102 ( 103 self.key, 104 tuple( 105 (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items() 106 ), 107 ) 108 ) 109 110 @property 111 def this(self): 112 """ 113 Retrieves the argument with key "this". 114 """ 115 return self.args.get("this") 116 117 @property 118 def expression(self): 119 """ 120 Retrieves the argument with key "expression". 121 """ 122 return self.args.get("expression") 123 124 @property 125 def expressions(self): 126 """ 127 Retrieves the argument with key "expressions". 128 """ 129 return self.args.get("expressions") or [] 130 131 def text(self, key) -> str: 132 """ 133 Returns a textual representation of the argument corresponding to "key". This can only be used 134 for args that are strings or leaf Expression instances, such as identifiers and literals. 135 """ 136 field = self.args.get(key) 137 if isinstance(field, str): 138 return field 139 if isinstance(field, (Identifier, Literal, Var)): 140 return field.this 141 if isinstance(field, (Star, Null)): 142 return field.name 143 return "" 144 145 @property 146 def is_string(self) -> bool: 147 """ 148 Checks whether a Literal expression is a string. 149 """ 150 return isinstance(self, Literal) and self.args["is_string"] 151 152 @property 153 def is_number(self) -> bool: 154 """ 155 Checks whether a Literal expression is a number. 156 """ 157 return isinstance(self, Literal) and not self.args["is_string"] 158 159 @property 160 def is_int(self) -> bool: 161 """ 162 Checks whether a Literal expression is an integer. 163 """ 164 if self.is_number: 165 try: 166 int(self.name) 167 return True 168 except ValueError: 169 pass 170 return False 171 172 @property 173 def is_star(self) -> bool: 174 """Checks whether an expression is a star.""" 175 return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star)) 176 177 @property 178 def alias(self) -> str: 179 """ 180 Returns the alias of the expression, or an empty string if it's not aliased. 181 """ 182 if isinstance(self.args.get("alias"), TableAlias): 183 return self.args["alias"].name 184 return self.text("alias") 185 186 @property 187 def name(self) -> str: 188 return self.text("this") 189 190 @property 191 def alias_or_name(self): 192 return self.alias or self.name 193 194 @property 195 def output_name(self): 196 """ 197 Name of the output column if this expression is a selection. 198 199 If the Expression has no output name, an empty string is returned. 200 201 Example: 202 >>> from sqlglot import parse_one 203 >>> parse_one("SELECT a").expressions[0].output_name 204 'a' 205 >>> parse_one("SELECT b AS c").expressions[0].output_name 206 'c' 207 >>> parse_one("SELECT 1 + 2").expressions[0].output_name 208 '' 209 """ 210 return "" 211 212 @property 213 def type(self) -> t.Optional[DataType]: 214 return self._type 215 216 @type.setter 217 def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None: 218 if dtype and not isinstance(dtype, DataType): 219 dtype = DataType.build(dtype) 220 self._type = dtype # type: ignore 221 222 def __deepcopy__(self, memo): 223 copy = self.__class__(**deepcopy(self.args)) 224 copy.comments = self.comments 225 copy.type = self.type 226 return copy 227 228 def copy(self): 229 """ 230 Returns a deep copy of the expression. 231 """ 232 new = deepcopy(self) 233 new.parent = self.parent 234 for item, parent, _ in new.bfs(): 235 if isinstance(item, Expression) and parent: 236 item.parent = parent 237 return new 238 239 def append(self, arg_key, value): 240 """ 241 Appends value to arg_key if it's a list or sets it as a new list. 242 243 Args: 244 arg_key (str): name of the list expression arg 245 value (Any): value to append to the list 246 """ 247 if not isinstance(self.args.get(arg_key), list): 248 self.args[arg_key] = [] 249 self.args[arg_key].append(value) 250 self._set_parent(arg_key, value) 251 252 def set(self, arg_key, value): 253 """ 254 Sets `arg_key` to `value`. 255 256 Args: 257 arg_key (str): name of the expression arg. 258 value: value to set the arg to. 259 """ 260 self.args[arg_key] = value 261 self._set_parent(arg_key, value) 262 263 def _set_parent(self, arg_key, value): 264 if isinstance(value, Expression): 265 value.parent = self 266 value.arg_key = arg_key 267 elif isinstance(value, list): 268 for v in value: 269 if isinstance(v, Expression): 270 v.parent = self 271 v.arg_key = arg_key 272 273 @property 274 def depth(self): 275 """ 276 Returns the depth of this tree. 277 """ 278 if self.parent: 279 return self.parent.depth + 1 280 return 0 281 282 def find(self, *expression_types, bfs=True): 283 """ 284 Returns the first node in this tree which matches at least one of 285 the specified types. 286 287 Args: 288 expression_types (type): the expression type(s) to match. 289 290 Returns: 291 The node which matches the criteria or None if no such node was found. 292 """ 293 return next(self.find_all(*expression_types, bfs=bfs), None) 294 295 def find_all(self, *expression_types, bfs=True): 296 """ 297 Returns a generator object which visits all nodes in this tree and only 298 yields those that match at least one of the specified expression types. 299 300 Args: 301 expression_types (type): the expression type(s) to match. 302 303 Returns: 304 The generator object. 305 """ 306 for expression, _, _ in self.walk(bfs=bfs): 307 if isinstance(expression, expression_types): 308 yield expression 309 310 def find_ancestor(self, *expression_types): 311 """ 312 Returns a nearest parent matching expression_types. 313 314 Args: 315 expression_types (type): the expression type(s) to match. 316 317 Returns: 318 The parent node. 319 """ 320 ancestor = self.parent 321 while ancestor and not isinstance(ancestor, expression_types): 322 ancestor = ancestor.parent 323 return ancestor 324 325 @property 326 def parent_select(self): 327 """ 328 Returns the parent select statement. 329 """ 330 return self.find_ancestor(Select) 331 332 def walk(self, bfs=True, prune=None): 333 """ 334 Returns a generator object which visits all nodes in this tree. 335 336 Args: 337 bfs (bool): if set to True the BFS traversal order will be applied, 338 otherwise the DFS traversal will be used instead. 339 prune ((node, parent, arg_key) -> bool): callable that returns True if 340 the generator should stop traversing this branch of the tree. 341 342 Returns: 343 the generator object. 344 """ 345 if bfs: 346 yield from self.bfs(prune=prune) 347 else: 348 yield from self.dfs(prune=prune) 349 350 def dfs(self, parent=None, key=None, prune=None): 351 """ 352 Returns a generator object which visits all nodes in this tree in 353 the DFS (Depth-first) order. 354 355 Returns: 356 The generator object. 357 """ 358 parent = parent or self.parent 359 yield self, parent, key 360 if prune and prune(self, parent, key): 361 return 362 363 for k, v in self.args.items(): 364 for node in ensure_collection(v): 365 if isinstance(node, Expression): 366 yield from node.dfs(self, k, prune) 367 368 def bfs(self, prune=None): 369 """ 370 Returns a generator object which visits all nodes in this tree in 371 the BFS (Breadth-first) order. 372 373 Returns: 374 The generator object. 375 """ 376 queue = deque([(self, self.parent, None)]) 377 378 while queue: 379 item, parent, key = queue.popleft() 380 381 yield item, parent, key 382 if prune and prune(item, parent, key): 383 continue 384 385 if isinstance(item, Expression): 386 for k, v in item.args.items(): 387 for node in ensure_collection(v): 388 if isinstance(node, Expression): 389 queue.append((node, item, k)) 390 391 def unnest(self): 392 """ 393 Returns the first non parenthesis child or self. 394 """ 395 expression = self 396 while isinstance(expression, Paren): 397 expression = expression.this 398 return expression 399 400 def unalias(self): 401 """ 402 Returns the inner expression if this is an Alias. 403 """ 404 if isinstance(self, Alias): 405 return self.this 406 return self 407 408 def unnest_operands(self): 409 """ 410 Returns unnested operands as a tuple. 411 """ 412 return tuple(arg.unnest() for arg in self.args.values() if arg) 413 414 def flatten(self, unnest=True): 415 """ 416 Returns a generator which yields child nodes who's parents are the same class. 417 418 A AND B AND C -> [A, B, C] 419 """ 420 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 421 if not isinstance(node, self.__class__): 422 yield node.unnest() if unnest else node 423 424 def __str__(self): 425 return self.sql() 426 427 def __repr__(self): 428 return self._to_s() 429 430 def sql(self, dialect: DialectType = None, **opts) -> str: 431 """ 432 Returns SQL string representation of this tree. 433 434 Args: 435 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 436 opts: other `sqlglot.generator.Generator` options. 437 438 Returns: 439 The SQL string. 440 """ 441 from sqlglot.dialects import Dialect 442 443 return Dialect.get_or_raise(dialect)().generate(self, **opts) 444 445 def _to_s(self, hide_missing: bool = True, level: int = 0) -> str: 446 indent = "" if not level else "\n" 447 indent += "".join([" "] * level) 448 left = f"({self.key.upper()} " 449 450 args: t.Dict[str, t.Any] = { 451 k: ", ".join( 452 v._to_s(hide_missing=hide_missing, level=level + 1) 453 if hasattr(v, "_to_s") 454 else str(v) 455 for v in ensure_collection(vs) 456 if v is not None 457 ) 458 for k, vs in self.args.items() 459 } 460 args["comments"] = self.comments 461 args["type"] = self.type 462 args = {k: v for k, v in args.items() if v or not hide_missing} 463 464 right = ", ".join(f"{k}: {v}" for k, v in args.items()) 465 right += ")" 466 467 return indent + left + right 468 469 def transform(self, fun, *args, copy=True, **kwargs): 470 """ 471 Recursively visits all tree nodes (excluding already transformed ones) 472 and applies the given transformation function to each node. 473 474 Args: 475 fun (function): a function which takes a node as an argument and returns a 476 new transformed node or the same node without modifications. If the function 477 returns None, then the corresponding node will be removed from the syntax tree. 478 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 479 modified in place. 480 481 Returns: 482 The transformed tree. 483 """ 484 node = self.copy() if copy else self 485 new_node = fun(node, *args, **kwargs) 486 487 if new_node is None or not isinstance(new_node, Expression): 488 return new_node 489 if new_node is not node: 490 new_node.parent = node.parent 491 return new_node 492 493 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 494 return new_node 495 496 def replace(self, expression): 497 """ 498 Swap out this expression with a new expression. 499 500 For example:: 501 502 >>> tree = Select().select("x").from_("tbl") 503 >>> tree.find(Column).replace(Column(this="y")) 504 (COLUMN this: y) 505 >>> tree.sql() 506 'SELECT y FROM tbl' 507 508 Args: 509 expression (Expression|None): new node 510 511 Returns: 512 The new expression or expressions. 513 """ 514 if not self.parent: 515 return expression 516 517 parent = self.parent 518 self.parent = None 519 520 replace_children(parent, lambda child: expression if child is self else child) 521 return expression 522 523 def pop(self): 524 """ 525 Remove this expression from its AST. 526 """ 527 self.replace(None) 528 529 def assert_is(self, type_): 530 """ 531 Assert that this `Expression` is an instance of `type_`. 532 533 If it is NOT an instance of `type_`, this raises an assertion error. 534 Otherwise, this returns this expression. 535 536 Examples: 537 This is useful for type security in chained expressions: 538 539 >>> import sqlglot 540 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 541 'SELECT x, z FROM y' 542 """ 543 assert isinstance(self, type_) 544 return self 545 546 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 547 """ 548 Checks if this expression is valid (e.g. all mandatory args are set). 549 550 Args: 551 args: a sequence of values that were used to instantiate a Func expression. This is used 552 to check that the provided arguments don't exceed the function argument limit. 553 554 Returns: 555 A list of error messages for all possible errors that were found. 556 """ 557 errors: t.List[str] = [] 558 559 for k in self.args: 560 if k not in self.arg_types: 561 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 562 for k, mandatory in self.arg_types.items(): 563 v = self.args.get(k) 564 if mandatory and (v is None or (isinstance(v, list) and not v)): 565 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 566 567 if ( 568 args 569 and isinstance(self, Func) 570 and len(args) > len(self.arg_types) 571 and not self.is_var_len_args 572 ): 573 errors.append( 574 f"The number of provided arguments ({len(args)}) is greater than " 575 f"the maximum number of supported arguments ({len(self.arg_types)})" 576 ) 577 578 return errors 579 580 def dump(self): 581 """ 582 Dump this Expression to a JSON-serializable dict. 583 """ 584 from sqlglot.serde import dump 585 586 return dump(self) 587 588 @classmethod 589 def load(cls, obj): 590 """ 591 Load a dict (as returned by `Expression.dump`) into an Expression instance. 592 """ 593 from sqlglot.serde import load 594 595 return load(obj) 596 597 598IntoType = t.Union[ 599 str, 600 t.Type[Expression], 601 t.Collection[t.Union[str, t.Type[Expression]]], 602] 603 604 605class Condition(Expression): 606 def and_(self, *expressions, dialect=None, **opts): 607 """ 608 AND this condition with one or multiple expressions. 609 610 Example: 611 >>> condition("x=1").and_("y=1").sql() 612 'x = 1 AND y = 1' 613 614 Args: 615 *expressions (str | Expression): the SQL code strings to parse. 616 If an `Expression` instance is passed, it will be used as-is. 617 dialect (str): the dialect used to parse the input expression. 618 opts (kwargs): other options to use to parse the input expressions. 619 620 Returns: 621 And: the new condition. 622 """ 623 return and_(self, *expressions, dialect=dialect, **opts) 624 625 def or_(self, *expressions, dialect=None, **opts): 626 """ 627 OR this condition with one or multiple expressions. 628 629 Example: 630 >>> condition("x=1").or_("y=1").sql() 631 'x = 1 OR y = 1' 632 633 Args: 634 *expressions (str | Expression): the SQL code strings to parse. 635 If an `Expression` instance is passed, it will be used as-is. 636 dialect (str): the dialect used to parse the input expression. 637 opts (kwargs): other options to use to parse the input expressions. 638 639 Returns: 640 Or: the new condition. 641 """ 642 return or_(self, *expressions, dialect=dialect, **opts) 643 644 def not_(self): 645 """ 646 Wrap this condition with NOT. 647 648 Example: 649 >>> condition("x=1").not_().sql() 650 'NOT x = 1' 651 652 Returns: 653 Not: the new condition. 654 """ 655 return not_(self) 656 657 658class Predicate(Condition): 659 """Relationships like x = y, x > 1, x >= y.""" 660 661 662class DerivedTable(Expression): 663 @property 664 def alias_column_names(self): 665 table_alias = self.args.get("alias") 666 if not table_alias: 667 return [] 668 column_list = table_alias.assert_is(TableAlias).args.get("columns") or [] 669 return [c.name for c in column_list] 670 671 @property 672 def selects(self): 673 alias = self.args.get("alias") 674 675 if alias: 676 return alias.columns 677 return [] 678 679 @property 680 def named_selects(self): 681 return [select.output_name for select in self.selects] 682 683 684class Unionable(Expression): 685 def union(self, expression, distinct=True, dialect=None, **opts): 686 """ 687 Builds a UNION expression. 688 689 Example: 690 >>> import sqlglot 691 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 692 'SELECT * FROM foo UNION SELECT * FROM bla' 693 694 Args: 695 expression (str | Expression): the SQL code string. 696 If an `Expression` instance is passed, it will be used as-is. 697 distinct (bool): set the DISTINCT flag if and only if this is true. 698 dialect (str): the dialect used to parse the input expression. 699 opts (kwargs): other options to use to parse the input expressions. 700 Returns: 701 Union: the Union expression. 702 """ 703 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 704 705 def intersect(self, expression, distinct=True, dialect=None, **opts): 706 """ 707 Builds an INTERSECT expression. 708 709 Example: 710 >>> import sqlglot 711 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 712 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 713 714 Args: 715 expression (str | Expression): the SQL code string. 716 If an `Expression` instance is passed, it will be used as-is. 717 distinct (bool): set the DISTINCT flag if and only if this is true. 718 dialect (str): the dialect used to parse the input expression. 719 opts (kwargs): other options to use to parse the input expressions. 720 Returns: 721 Intersect: the Intersect expression 722 """ 723 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 724 725 def except_(self, expression, distinct=True, dialect=None, **opts): 726 """ 727 Builds an EXCEPT expression. 728 729 Example: 730 >>> import sqlglot 731 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 732 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 733 734 Args: 735 expression (str | Expression): the SQL code string. 736 If an `Expression` instance is passed, it will be used as-is. 737 distinct (bool): set the DISTINCT flag if and only if this is true. 738 dialect (str): the dialect used to parse the input expression. 739 opts (kwargs): other options to use to parse the input expressions. 740 Returns: 741 Except: the Except expression 742 """ 743 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 744 745 746class UDTF(DerivedTable, Unionable): 747 pass 748 749 750class Cache(Expression): 751 arg_types = { 752 "with": False, 753 "this": True, 754 "lazy": False, 755 "options": False, 756 "expression": False, 757 } 758 759 760class Uncache(Expression): 761 arg_types = {"this": True, "exists": False} 762 763 764class Create(Expression): 765 arg_types = { 766 "with": False, 767 "this": True, 768 "kind": True, 769 "expression": False, 770 "set": False, 771 "multiset": False, 772 "global_temporary": False, 773 "volatile": False, 774 "exists": False, 775 "properties": False, 776 "temporary": False, 777 "transient": False, 778 "external": False, 779 "replace": False, 780 "unique": False, 781 "materialized": False, 782 "data": False, 783 "statistics": False, 784 "no_primary_index": False, 785 "indexes": False, 786 "no_schema_binding": False, 787 "begin": False, 788 } 789 790 791class Describe(Expression): 792 arg_types = {"this": True, "kind": False} 793 794 795class Set(Expression): 796 arg_types = {"expressions": True} 797 798 799class SetItem(Expression): 800 arg_types = { 801 "this": False, 802 "expressions": False, 803 "kind": False, 804 "collate": False, # MySQL SET NAMES statement 805 "global": False, 806 } 807 808 809class Show(Expression): 810 arg_types = { 811 "this": True, 812 "target": False, 813 "offset": False, 814 "limit": False, 815 "like": False, 816 "where": False, 817 "db": False, 818 "full": False, 819 "mutex": False, 820 "query": False, 821 "channel": False, 822 "global": False, 823 "log": False, 824 "position": False, 825 "types": False, 826 } 827 828 829class UserDefinedFunction(Expression): 830 arg_types = {"this": True, "expressions": False, "wrapped": False} 831 832 833class CharacterSet(Expression): 834 arg_types = {"this": True, "default": False} 835 836 837class With(Expression): 838 arg_types = {"expressions": True, "recursive": False} 839 840 @property 841 def recursive(self) -> bool: 842 return bool(self.args.get("recursive")) 843 844 845class WithinGroup(Expression): 846 arg_types = {"this": True, "expression": False} 847 848 849class CTE(DerivedTable): 850 arg_types = {"this": True, "alias": True} 851 852 853class TableAlias(Expression): 854 arg_types = {"this": False, "columns": False} 855 856 @property 857 def columns(self): 858 return self.args.get("columns") or [] 859 860 861class BitString(Condition): 862 pass 863 864 865class HexString(Condition): 866 pass 867 868 869class ByteString(Condition): 870 pass 871 872 873class Column(Condition): 874 arg_types = {"this": True, "table": False, "db": False, "catalog": False} 875 876 @property 877 def table(self) -> str: 878 return self.text("table") 879 880 @property 881 def db(self) -> str: 882 return self.text("db") 883 884 @property 885 def catalog(self) -> str: 886 return self.text("catalog") 887 888 @property 889 def output_name(self) -> str: 890 return self.name 891 892 893class ColumnDef(Expression): 894 arg_types = { 895 "this": True, 896 "kind": False, 897 "constraints": False, 898 "exists": False, 899 } 900 901 902class AlterColumn(Expression): 903 arg_types = { 904 "this": True, 905 "dtype": False, 906 "collate": False, 907 "using": False, 908 "default": False, 909 "drop": False, 910 } 911 912 913class RenameTable(Expression): 914 pass 915 916 917class ColumnConstraint(Expression): 918 arg_types = {"this": False, "kind": True} 919 920 921class ColumnConstraintKind(Expression): 922 pass 923 924 925class AutoIncrementColumnConstraint(ColumnConstraintKind): 926 pass 927 928 929class CaseSpecificColumnConstraint(ColumnConstraintKind): 930 arg_types = {"not_": True} 931 932 933class CharacterSetColumnConstraint(ColumnConstraintKind): 934 arg_types = {"this": True} 935 936 937class CheckColumnConstraint(ColumnConstraintKind): 938 pass 939 940 941class CollateColumnConstraint(ColumnConstraintKind): 942 pass 943 944 945class CommentColumnConstraint(ColumnConstraintKind): 946 pass 947 948 949class CompressColumnConstraint(ColumnConstraintKind): 950 pass 951 952 953class DateFormatColumnConstraint(ColumnConstraintKind): 954 arg_types = {"this": True} 955 956 957class DefaultColumnConstraint(ColumnConstraintKind): 958 pass 959 960 961class EncodeColumnConstraint(ColumnConstraintKind): 962 pass 963 964 965class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind): 966 # this: True -> ALWAYS, this: False -> BY DEFAULT 967 arg_types = { 968 "this": False, 969 "start": False, 970 "increment": False, 971 "minvalue": False, 972 "maxvalue": False, 973 "cycle": False, 974 } 975 976 977class InlineLengthColumnConstraint(ColumnConstraintKind): 978 pass 979 980 981class NotNullColumnConstraint(ColumnConstraintKind): 982 arg_types = {"allow_null": False} 983 984 985class PrimaryKeyColumnConstraint(ColumnConstraintKind): 986 arg_types = {"desc": False} 987 988 989class TitleColumnConstraint(ColumnConstraintKind): 990 pass 991 992 993class UniqueColumnConstraint(ColumnConstraintKind): 994 arg_types: t.Dict[str, t.Any] = {} 995 996 997class UppercaseColumnConstraint(ColumnConstraintKind): 998 arg_types: t.Dict[str, t.Any] = {} 999 1000 1001class PathColumnConstraint(ColumnConstraintKind): 1002 pass 1003 1004 1005class Constraint(Expression): 1006 arg_types = {"this": True, "expressions": True} 1007 1008 1009class Delete(Expression): 1010 arg_types = {"with": False, "this": False, "using": False, "where": False} 1011 1012 1013class Drop(Expression): 1014 arg_types = { 1015 "this": False, 1016 "kind": False, 1017 "exists": False, 1018 "temporary": False, 1019 "materialized": False, 1020 "cascade": False, 1021 } 1022 1023 1024class Filter(Expression): 1025 arg_types = {"this": True, "expression": True} 1026 1027 1028class Check(Expression): 1029 pass 1030 1031 1032class Directory(Expression): 1033 # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html 1034 arg_types = {"this": True, "local": False, "row_format": False} 1035 1036 1037class ForeignKey(Expression): 1038 arg_types = { 1039 "expressions": True, 1040 "reference": False, 1041 "delete": False, 1042 "update": False, 1043 } 1044 1045 1046class PrimaryKey(Expression): 1047 arg_types = {"expressions": True, "options": False} 1048 1049 1050class Unique(Expression): 1051 arg_types = {"expressions": True} 1052 1053 1054# https://www.postgresql.org/docs/9.1/sql-selectinto.html 1055# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples 1056class Into(Expression): 1057 arg_types = {"this": True, "temporary": False, "unlogged": False} 1058 1059 1060class From(Expression): 1061 arg_types = {"expressions": True} 1062 1063 1064class Having(Expression): 1065 pass 1066 1067 1068class Hint(Expression): 1069 arg_types = {"expressions": True} 1070 1071 1072class JoinHint(Expression): 1073 arg_types = {"this": True, "expressions": True} 1074 1075 1076class Identifier(Expression): 1077 arg_types = {"this": True, "quoted": False} 1078 1079 @property 1080 def quoted(self): 1081 return bool(self.args.get("quoted")) 1082 1083 def __eq__(self, other): 1084 return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this) 1085 1086 def __hash__(self): 1087 return hash((self.key, self.this.lower())) 1088 1089 @property 1090 def output_name(self): 1091 return self.name 1092 1093 1094class Index(Expression): 1095 arg_types = { 1096 "this": False, 1097 "table": False, 1098 "where": False, 1099 "columns": False, 1100 "unique": False, 1101 "primary": False, 1102 "amp": False, # teradata 1103 } 1104 1105 1106class Insert(Expression): 1107 arg_types = { 1108 "with": False, 1109 "this": True, 1110 "expression": False, 1111 "overwrite": False, 1112 "exists": False, 1113 "partition": False, 1114 "alternative": False, 1115 } 1116 1117 1118# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html 1119class Introducer(Expression): 1120 arg_types = {"this": True, "expression": True} 1121 1122 1123# national char, like n'utf8' 1124class National(Expression): 1125 pass 1126 1127 1128class LoadData(Expression): 1129 arg_types = { 1130 "this": True, 1131 "local": False, 1132 "overwrite": False, 1133 "inpath": True, 1134 "partition": False, 1135 "input_format": False, 1136 "serde": False, 1137 } 1138 1139 1140class Partition(Expression): 1141 arg_types = {"expressions": True} 1142 1143 1144class Fetch(Expression): 1145 arg_types = {"direction": False, "count": False} 1146 1147 1148class Group(Expression): 1149 arg_types = { 1150 "expressions": False, 1151 "grouping_sets": False, 1152 "cube": False, 1153 "rollup": False, 1154 } 1155 1156 1157class Lambda(Expression): 1158 arg_types = {"this": True, "expressions": True} 1159 1160 1161class Limit(Expression): 1162 arg_types = {"this": False, "expression": True} 1163 1164 1165class Literal(Condition): 1166 arg_types = {"this": True, "is_string": True} 1167 1168 def __eq__(self, other): 1169 return ( 1170 isinstance(other, Literal) 1171 and self.this == other.this 1172 and self.args["is_string"] == other.args["is_string"] 1173 ) 1174 1175 def __hash__(self): 1176 return hash((self.key, self.this, self.args["is_string"])) 1177 1178 @classmethod 1179 def number(cls, number) -> Literal: 1180 return cls(this=str(number), is_string=False) 1181 1182 @classmethod 1183 def string(cls, string) -> Literal: 1184 return cls(this=str(string), is_string=True) 1185 1186 @property 1187 def output_name(self): 1188 return self.name 1189 1190 1191class Join(Expression): 1192 arg_types = { 1193 "this": True, 1194 "on": False, 1195 "side": False, 1196 "kind": False, 1197 "using": False, 1198 "natural": False, 1199 } 1200 1201 @property 1202 def kind(self): 1203 return self.text("kind").upper() 1204 1205 @property 1206 def side(self): 1207 return self.text("side").upper() 1208 1209 @property 1210 def alias_or_name(self): 1211 return self.this.alias_or_name 1212 1213 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1214 """ 1215 Append to or set the ON expressions. 1216 1217 Example: 1218 >>> import sqlglot 1219 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1220 'JOIN x ON y = 1' 1221 1222 Args: 1223 *expressions (str | Expression): the SQL code strings to parse. 1224 If an `Expression` instance is passed, it will be used as-is. 1225 Multiple expressions are combined with an AND operator. 1226 append (bool): if `True`, AND the new expressions to any existing expression. 1227 Otherwise, this resets the expression. 1228 dialect (str): the dialect used to parse the input expressions. 1229 copy (bool): if `False`, modify this expression instance in-place. 1230 opts (kwargs): other options to use to parse the input expressions. 1231 1232 Returns: 1233 Join: the modified join expression. 1234 """ 1235 join = _apply_conjunction_builder( 1236 *expressions, 1237 instance=self, 1238 arg="on", 1239 append=append, 1240 dialect=dialect, 1241 copy=copy, 1242 **opts, 1243 ) 1244 1245 if join.kind == "CROSS": 1246 join.set("kind", None) 1247 1248 return join 1249 1250 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1251 """ 1252 Append to or set the USING expressions. 1253 1254 Example: 1255 >>> import sqlglot 1256 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1257 'JOIN x USING (foo, bla)' 1258 1259 Args: 1260 *expressions (str | Expression): the SQL code strings to parse. 1261 If an `Expression` instance is passed, it will be used as-is. 1262 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1263 Otherwise, this resets the expression. 1264 dialect (str): the dialect used to parse the input expressions. 1265 copy (bool): if `False`, modify this expression instance in-place. 1266 opts (kwargs): other options to use to parse the input expressions. 1267 1268 Returns: 1269 Join: the modified join expression. 1270 """ 1271 join = _apply_list_builder( 1272 *expressions, 1273 instance=self, 1274 arg="using", 1275 append=append, 1276 dialect=dialect, 1277 copy=copy, 1278 **opts, 1279 ) 1280 1281 if join.kind == "CROSS": 1282 join.set("kind", None) 1283 1284 return join 1285 1286 1287class Lateral(UDTF): 1288 arg_types = {"this": True, "view": False, "outer": False, "alias": False} 1289 1290 1291class MatchRecognize(Expression): 1292 arg_types = { 1293 "partition_by": False, 1294 "order": False, 1295 "measures": False, 1296 "rows": False, 1297 "after": False, 1298 "pattern": False, 1299 "define": False, 1300 } 1301 1302 1303# Clickhouse FROM FINAL modifier 1304# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier 1305class Final(Expression): 1306 pass 1307 1308 1309class Offset(Expression): 1310 arg_types = {"this": False, "expression": True} 1311 1312 1313class Order(Expression): 1314 arg_types = {"this": False, "expressions": True} 1315 1316 1317# hive specific sorts 1318# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy 1319class Cluster(Order): 1320 pass 1321 1322 1323class Distribute(Order): 1324 pass 1325 1326 1327class Sort(Order): 1328 pass 1329 1330 1331class Ordered(Expression): 1332 arg_types = {"this": True, "desc": True, "nulls_first": True} 1333 1334 1335class Property(Expression): 1336 arg_types = {"this": True, "value": True} 1337 1338 1339class AlgorithmProperty(Property): 1340 arg_types = {"this": True} 1341 1342 1343class DefinerProperty(Property): 1344 arg_types = {"this": True} 1345 1346 1347class SqlSecurityProperty(Property): 1348 arg_types = {"definer": True} 1349 1350 1351class TableFormatProperty(Property): 1352 arg_types = {"this": True} 1353 1354 1355class PartitionedByProperty(Property): 1356 arg_types = {"this": True} 1357 1358 1359class FileFormatProperty(Property): 1360 arg_types = {"this": True} 1361 1362 1363class DistKeyProperty(Property): 1364 arg_types = {"this": True} 1365 1366 1367class SortKeyProperty(Property): 1368 arg_types = {"this": True, "compound": False} 1369 1370 1371class DistStyleProperty(Property): 1372 arg_types = {"this": True} 1373 1374 1375class LikeProperty(Property): 1376 arg_types = {"this": True, "expressions": False} 1377 1378 1379class LocationProperty(Property): 1380 arg_types = {"this": True} 1381 1382 1383class EngineProperty(Property): 1384 arg_types = {"this": True} 1385 1386 1387class AutoIncrementProperty(Property): 1388 arg_types = {"this": True} 1389 1390 1391class CharacterSetProperty(Property): 1392 arg_types = {"this": True, "default": True} 1393 1394 1395class CollateProperty(Property): 1396 arg_types = {"this": True} 1397 1398 1399class SchemaCommentProperty(Property): 1400 arg_types = {"this": True} 1401 1402 1403class ReturnsProperty(Property): 1404 arg_types = {"this": True, "is_table": False, "table": False} 1405 1406 1407class LanguageProperty(Property): 1408 arg_types = {"this": True} 1409 1410 1411class ExecuteAsProperty(Property): 1412 arg_types = {"this": True} 1413 1414 1415class VolatilityProperty(Property): 1416 arg_types = {"this": True} 1417 1418 1419class RowFormatDelimitedProperty(Property): 1420 # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml 1421 arg_types = { 1422 "fields": False, 1423 "escaped": False, 1424 "collection_items": False, 1425 "map_keys": False, 1426 "lines": False, 1427 "null": False, 1428 "serde": False, 1429 } 1430 1431 1432class RowFormatSerdeProperty(Property): 1433 arg_types = {"this": True} 1434 1435 1436class SerdeProperties(Property): 1437 arg_types = {"expressions": True} 1438 1439 1440class FallbackProperty(Property): 1441 arg_types = {"no": True, "protection": False} 1442 1443 1444class WithJournalTableProperty(Property): 1445 arg_types = {"this": True} 1446 1447 1448class LogProperty(Property): 1449 arg_types = {"no": True} 1450 1451 1452class JournalProperty(Property): 1453 arg_types = {"no": True, "dual": False, "before": False} 1454 1455 1456class AfterJournalProperty(Property): 1457 arg_types = {"no": True, "dual": False, "local": False} 1458 1459 1460class ChecksumProperty(Property): 1461 arg_types = {"on": False, "default": False} 1462 1463 1464class FreespaceProperty(Property): 1465 arg_types = {"this": True, "percent": False} 1466 1467 1468class MergeBlockRatioProperty(Property): 1469 arg_types = {"this": False, "no": False, "default": False, "percent": False} 1470 1471 1472class DataBlocksizeProperty(Property): 1473 arg_types = {"size": False, "units": False, "min": False, "default": False} 1474 1475 1476class BlockCompressionProperty(Property): 1477 arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True} 1478 1479 1480class IsolatedLoadingProperty(Property): 1481 arg_types = { 1482 "no": True, 1483 "concurrent": True, 1484 "for_all": True, 1485 "for_insert": True, 1486 "for_none": True, 1487 } 1488 1489 1490class LockingProperty(Property): 1491 arg_types = { 1492 "this": False, 1493 "kind": True, 1494 "for_or_in": True, 1495 "lock_type": True, 1496 "override": False, 1497 } 1498 1499 1500class Properties(Expression): 1501 arg_types = {"expressions": True} 1502 1503 NAME_TO_PROPERTY = { 1504 "ALGORITHM": AlgorithmProperty, 1505 "AUTO_INCREMENT": AutoIncrementProperty, 1506 "CHARACTER SET": CharacterSetProperty, 1507 "COLLATE": CollateProperty, 1508 "COMMENT": SchemaCommentProperty, 1509 "DEFINER": DefinerProperty, 1510 "DISTKEY": DistKeyProperty, 1511 "DISTSTYLE": DistStyleProperty, 1512 "ENGINE": EngineProperty, 1513 "EXECUTE AS": ExecuteAsProperty, 1514 "FORMAT": FileFormatProperty, 1515 "LANGUAGE": LanguageProperty, 1516 "LOCATION": LocationProperty, 1517 "PARTITIONED_BY": PartitionedByProperty, 1518 "RETURNS": ReturnsProperty, 1519 "SORTKEY": SortKeyProperty, 1520 "TABLE_FORMAT": TableFormatProperty, 1521 } 1522 1523 PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()} 1524 1525 # CREATE property locations 1526 # Form: schema specified 1527 # create [POST_CREATE] 1528 # table a [POST_NAME] 1529 # (b int) [POST_SCHEMA] 1530 # with ([POST_WITH]) 1531 # index (b) [POST_INDEX] 1532 # 1533 # Form: alias selection 1534 # create [POST_CREATE] 1535 # table a [POST_NAME] 1536 # as [POST_ALIAS] (select * from b) 1537 # index (c) [POST_INDEX] 1538 class Location(AutoName): 1539 POST_CREATE = auto() 1540 POST_NAME = auto() 1541 POST_SCHEMA = auto() 1542 POST_WITH = auto() 1543 POST_ALIAS = auto() 1544 POST_INDEX = auto() 1545 UNSUPPORTED = auto() 1546 1547 @classmethod 1548 def from_dict(cls, properties_dict) -> Properties: 1549 expressions = [] 1550 for key, value in properties_dict.items(): 1551 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1552 if property_cls: 1553 expressions.append(property_cls(this=convert(value))) 1554 else: 1555 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1556 1557 return cls(expressions=expressions) 1558 1559 1560class Qualify(Expression): 1561 pass 1562 1563 1564# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql 1565class Return(Expression): 1566 pass 1567 1568 1569class Reference(Expression): 1570 arg_types = {"this": True, "expressions": False, "options": False} 1571 1572 1573class Tuple(Expression): 1574 arg_types = {"expressions": False} 1575 1576 1577class Subqueryable(Unionable): 1578 def subquery(self, alias=None, copy=True) -> Subquery: 1579 """ 1580 Convert this expression to an aliased expression that can be used as a Subquery. 1581 1582 Example: 1583 >>> subquery = Select().select("x").from_("tbl").subquery() 1584 >>> Select().select("x").from_(subquery).sql() 1585 'SELECT x FROM (SELECT x FROM tbl)' 1586 1587 Args: 1588 alias (str | Identifier): an optional alias for the subquery 1589 copy (bool): if `False`, modify this expression instance in-place. 1590 1591 Returns: 1592 Alias: the subquery 1593 """ 1594 instance = _maybe_copy(self, copy) 1595 return Subquery( 1596 this=instance, 1597 alias=TableAlias(this=to_identifier(alias)), 1598 ) 1599 1600 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1601 raise NotImplementedError 1602 1603 @property 1604 def ctes(self): 1605 with_ = self.args.get("with") 1606 if not with_: 1607 return [] 1608 return with_.expressions 1609 1610 @property 1611 def selects(self): 1612 raise NotImplementedError("Subqueryable objects must implement `selects`") 1613 1614 @property 1615 def named_selects(self): 1616 raise NotImplementedError("Subqueryable objects must implement `named_selects`") 1617 1618 def with_( 1619 self, 1620 alias, 1621 as_, 1622 recursive=None, 1623 append=True, 1624 dialect=None, 1625 copy=True, 1626 **opts, 1627 ): 1628 """ 1629 Append to or set the common table expressions. 1630 1631 Example: 1632 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1633 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1634 1635 Args: 1636 alias (str | Expression): the SQL code string to parse as the table name. 1637 If an `Expression` instance is passed, this is used as-is. 1638 as_ (str | Expression): the SQL code string to parse as the table expression. 1639 If an `Expression` instance is passed, it will be used as-is. 1640 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1641 append (bool): if `True`, add to any existing expressions. 1642 Otherwise, this resets the expressions. 1643 dialect (str): the dialect used to parse the input expression. 1644 copy (bool): if `False`, modify this expression instance in-place. 1645 opts (kwargs): other options to use to parse the input expressions. 1646 1647 Returns: 1648 Select: the modified expression. 1649 """ 1650 alias_expression = maybe_parse( 1651 alias, 1652 dialect=dialect, 1653 into=TableAlias, 1654 **opts, 1655 ) 1656 as_expression = maybe_parse( 1657 as_, 1658 dialect=dialect, 1659 **opts, 1660 ) 1661 cte = CTE( 1662 this=as_expression, 1663 alias=alias_expression, 1664 ) 1665 return _apply_child_list_builder( 1666 cte, 1667 instance=self, 1668 arg="with", 1669 append=append, 1670 copy=copy, 1671 into=With, 1672 properties={"recursive": recursive or False}, 1673 ) 1674 1675 1676QUERY_MODIFIERS = { 1677 "match": False, 1678 "laterals": False, 1679 "joins": False, 1680 "pivots": False, 1681 "where": False, 1682 "group": False, 1683 "having": False, 1684 "qualify": False, 1685 "windows": False, 1686 "distribute": False, 1687 "sort": False, 1688 "cluster": False, 1689 "order": False, 1690 "limit": False, 1691 "offset": False, 1692 "lock": False, 1693} 1694 1695 1696class Table(Expression): 1697 arg_types = { 1698 "this": True, 1699 "alias": False, 1700 "db": False, 1701 "catalog": False, 1702 "laterals": False, 1703 "joins": False, 1704 "pivots": False, 1705 "hints": False, 1706 "system_time": False, 1707 } 1708 1709 @property 1710 def db(self) -> str: 1711 return self.text("db") 1712 1713 @property 1714 def catalog(self) -> str: 1715 return self.text("catalog") 1716 1717 1718# See the TSQL "Querying data in a system-versioned temporal table" page 1719class SystemTime(Expression): 1720 arg_types = { 1721 "this": False, 1722 "expression": False, 1723 "kind": True, 1724 } 1725 1726 1727class Union(Subqueryable): 1728 arg_types = { 1729 "with": False, 1730 "this": True, 1731 "expression": True, 1732 "distinct": False, 1733 **QUERY_MODIFIERS, 1734 } 1735 1736 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1737 """ 1738 Set the LIMIT expression. 1739 1740 Example: 1741 >>> select("1").union(select("1")).limit(1).sql() 1742 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1743 1744 Args: 1745 expression (str | int | Expression): the SQL code string to parse. 1746 This can also be an integer. 1747 If a `Limit` instance is passed, this is used as-is. 1748 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1749 dialect (str): the dialect used to parse the input expression. 1750 copy (bool): if `False`, modify this expression instance in-place. 1751 opts (kwargs): other options to use to parse the input expressions. 1752 1753 Returns: 1754 Select: The limited subqueryable. 1755 """ 1756 return ( 1757 select("*") 1758 .from_(self.subquery(alias="_l_0", copy=copy)) 1759 .limit(expression, dialect=dialect, copy=False, **opts) 1760 ) 1761 1762 def select( 1763 self, 1764 *expressions: str | Expression, 1765 append: bool = True, 1766 dialect: DialectType = None, 1767 copy: bool = True, 1768 **opts, 1769 ) -> Union: 1770 """Append to or set the SELECT of the union recursively. 1771 1772 Example: 1773 >>> from sqlglot import parse_one 1774 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1775 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1776 1777 Args: 1778 *expressions: the SQL code strings to parse. 1779 If an `Expression` instance is passed, it will be used as-is. 1780 append: if `True`, add to any existing expressions. 1781 Otherwise, this resets the expressions. 1782 dialect: the dialect used to parse the input expressions. 1783 copy: if `False`, modify this expression instance in-place. 1784 opts: other options to use to parse the input expressions. 1785 1786 Returns: 1787 Union: the modified expression. 1788 """ 1789 this = self.copy() if copy else self 1790 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1791 this.expression.unnest().select( 1792 *expressions, append=append, dialect=dialect, copy=False, **opts 1793 ) 1794 return this 1795 1796 @property 1797 def named_selects(self): 1798 return self.this.unnest().named_selects 1799 1800 @property 1801 def selects(self): 1802 return self.this.unnest().selects 1803 1804 @property 1805 def left(self): 1806 return self.this 1807 1808 @property 1809 def right(self): 1810 return self.expression 1811 1812 1813class Except(Union): 1814 pass 1815 1816 1817class Intersect(Union): 1818 pass 1819 1820 1821class Unnest(UDTF): 1822 arg_types = { 1823 "expressions": True, 1824 "ordinality": False, 1825 "alias": False, 1826 "offset": False, 1827 } 1828 1829 1830class Update(Expression): 1831 arg_types = { 1832 "with": False, 1833 "this": False, 1834 "expressions": True, 1835 "from": False, 1836 "where": False, 1837 } 1838 1839 1840class Values(UDTF): 1841 arg_types = { 1842 "expressions": True, 1843 "ordinality": False, 1844 "alias": False, 1845 } 1846 1847 1848class Var(Expression): 1849 pass 1850 1851 1852class Schema(Expression): 1853 arg_types = {"this": False, "expressions": False} 1854 1855 1856# Used to represent the FOR UPDATE and FOR SHARE locking read types. 1857# https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html 1858class Lock(Expression): 1859 arg_types = {"update": True} 1860 1861 1862class Select(Subqueryable): 1863 arg_types = { 1864 "with": False, 1865 "expressions": False, 1866 "hint": False, 1867 "distinct": False, 1868 "into": False, 1869 "from": False, 1870 **QUERY_MODIFIERS, 1871 } 1872 1873 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1874 """ 1875 Set the FROM expression. 1876 1877 Example: 1878 >>> Select().from_("tbl").select("x").sql() 1879 'SELECT x FROM tbl' 1880 1881 Args: 1882 *expressions (str | Expression): the SQL code strings to parse. 1883 If a `From` instance is passed, this is used as-is. 1884 If another `Expression` instance is passed, it will be wrapped in a `From`. 1885 append (bool): if `True`, add to any existing expressions. 1886 Otherwise, this flattens all the `From` expression into a single expression. 1887 dialect (str): the dialect used to parse the input expression. 1888 copy (bool): if `False`, modify this expression instance in-place. 1889 opts (kwargs): other options to use to parse the input expressions. 1890 1891 Returns: 1892 Select: the modified expression. 1893 """ 1894 return _apply_child_list_builder( 1895 *expressions, 1896 instance=self, 1897 arg="from", 1898 append=append, 1899 copy=copy, 1900 prefix="FROM", 1901 into=From, 1902 dialect=dialect, 1903 **opts, 1904 ) 1905 1906 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1907 """ 1908 Set the GROUP BY expression. 1909 1910 Example: 1911 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1912 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1913 1914 Args: 1915 *expressions (str | Expression): the SQL code strings to parse. 1916 If a `Group` instance is passed, this is used as-is. 1917 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1918 If nothing is passed in then a group by is not applied to the expression 1919 append (bool): if `True`, add to any existing expressions. 1920 Otherwise, this flattens all the `Group` expression into a single expression. 1921 dialect (str): the dialect used to parse the input expression. 1922 copy (bool): if `False`, modify this expression instance in-place. 1923 opts (kwargs): other options to use to parse the input expressions. 1924 1925 Returns: 1926 Select: the modified expression. 1927 """ 1928 if not expressions: 1929 return self if not copy else self.copy() 1930 return _apply_child_list_builder( 1931 *expressions, 1932 instance=self, 1933 arg="group", 1934 append=append, 1935 copy=copy, 1936 prefix="GROUP BY", 1937 into=Group, 1938 dialect=dialect, 1939 **opts, 1940 ) 1941 1942 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1943 """ 1944 Set the ORDER BY expression. 1945 1946 Example: 1947 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1948 'SELECT x FROM tbl ORDER BY x DESC' 1949 1950 Args: 1951 *expressions (str | Expression): the SQL code strings to parse. 1952 If a `Group` instance is passed, this is used as-is. 1953 If another `Expression` instance is passed, it will be wrapped in a `Order`. 1954 append (bool): if `True`, add to any existing expressions. 1955 Otherwise, this flattens all the `Order` expression into a single expression. 1956 dialect (str): the dialect used to parse the input expression. 1957 copy (bool): if `False`, modify this expression instance in-place. 1958 opts (kwargs): other options to use to parse the input expressions. 1959 1960 Returns: 1961 Select: the modified expression. 1962 """ 1963 return _apply_child_list_builder( 1964 *expressions, 1965 instance=self, 1966 arg="order", 1967 append=append, 1968 copy=copy, 1969 prefix="ORDER BY", 1970 into=Order, 1971 dialect=dialect, 1972 **opts, 1973 ) 1974 1975 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1976 """ 1977 Set the SORT BY expression. 1978 1979 Example: 1980 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 1981 'SELECT x FROM tbl SORT BY x DESC' 1982 1983 Args: 1984 *expressions (str | Expression): the SQL code strings to parse. 1985 If a `Group` instance is passed, this is used as-is. 1986 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 1987 append (bool): if `True`, add to any existing expressions. 1988 Otherwise, this flattens all the `Order` expression into a single expression. 1989 dialect (str): the dialect used to parse the input expression. 1990 copy (bool): if `False`, modify this expression instance in-place. 1991 opts (kwargs): other options to use to parse the input expressions. 1992 1993 Returns: 1994 Select: the modified expression. 1995 """ 1996 return _apply_child_list_builder( 1997 *expressions, 1998 instance=self, 1999 arg="sort", 2000 append=append, 2001 copy=copy, 2002 prefix="SORT BY", 2003 into=Sort, 2004 dialect=dialect, 2005 **opts, 2006 ) 2007 2008 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2009 """ 2010 Set the CLUSTER BY expression. 2011 2012 Example: 2013 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2014 'SELECT x FROM tbl CLUSTER BY x DESC' 2015 2016 Args: 2017 *expressions (str | Expression): the SQL code strings to parse. 2018 If a `Group` instance is passed, this is used as-is. 2019 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2020 append (bool): if `True`, add to any existing expressions. 2021 Otherwise, this flattens all the `Order` expression into a single expression. 2022 dialect (str): the dialect used to parse the input expression. 2023 copy (bool): if `False`, modify this expression instance in-place. 2024 opts (kwargs): other options to use to parse the input expressions. 2025 2026 Returns: 2027 Select: the modified expression. 2028 """ 2029 return _apply_child_list_builder( 2030 *expressions, 2031 instance=self, 2032 arg="cluster", 2033 append=append, 2034 copy=copy, 2035 prefix="CLUSTER BY", 2036 into=Cluster, 2037 dialect=dialect, 2038 **opts, 2039 ) 2040 2041 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2042 """ 2043 Set the LIMIT expression. 2044 2045 Example: 2046 >>> Select().from_("tbl").select("x").limit(10).sql() 2047 'SELECT x FROM tbl LIMIT 10' 2048 2049 Args: 2050 expression (str | int | Expression): the SQL code string to parse. 2051 This can also be an integer. 2052 If a `Limit` instance is passed, this is used as-is. 2053 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2054 dialect (str): the dialect used to parse the input expression. 2055 copy (bool): if `False`, modify this expression instance in-place. 2056 opts (kwargs): other options to use to parse the input expressions. 2057 2058 Returns: 2059 Select: the modified expression. 2060 """ 2061 return _apply_builder( 2062 expression=expression, 2063 instance=self, 2064 arg="limit", 2065 into=Limit, 2066 prefix="LIMIT", 2067 dialect=dialect, 2068 copy=copy, 2069 **opts, 2070 ) 2071 2072 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2073 """ 2074 Set the OFFSET expression. 2075 2076 Example: 2077 >>> Select().from_("tbl").select("x").offset(10).sql() 2078 'SELECT x FROM tbl OFFSET 10' 2079 2080 Args: 2081 expression (str | int | Expression): the SQL code string to parse. 2082 This can also be an integer. 2083 If a `Offset` instance is passed, this is used as-is. 2084 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2085 dialect (str): the dialect used to parse the input expression. 2086 copy (bool): if `False`, modify this expression instance in-place. 2087 opts (kwargs): other options to use to parse the input expressions. 2088 2089 Returns: 2090 Select: the modified expression. 2091 """ 2092 return _apply_builder( 2093 expression=expression, 2094 instance=self, 2095 arg="offset", 2096 into=Offset, 2097 prefix="OFFSET", 2098 dialect=dialect, 2099 copy=copy, 2100 **opts, 2101 ) 2102 2103 def select( 2104 self, 2105 *expressions: str | Expression, 2106 append: bool = True, 2107 dialect: DialectType = None, 2108 copy: bool = True, 2109 **opts, 2110 ) -> Select: 2111 """ 2112 Append to or set the SELECT expressions. 2113 2114 Example: 2115 >>> Select().select("x", "y").sql() 2116 'SELECT x, y' 2117 2118 Args: 2119 *expressions: the SQL code strings to parse. 2120 If an `Expression` instance is passed, it will be used as-is. 2121 append: if `True`, add to any existing expressions. 2122 Otherwise, this resets the expressions. 2123 dialect: the dialect used to parse the input expressions. 2124 copy: if `False`, modify this expression instance in-place. 2125 opts: other options to use to parse the input expressions. 2126 2127 Returns: 2128 Select: the modified expression. 2129 """ 2130 return _apply_list_builder( 2131 *expressions, 2132 instance=self, 2133 arg="expressions", 2134 append=append, 2135 dialect=dialect, 2136 copy=copy, 2137 **opts, 2138 ) 2139 2140 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2141 """ 2142 Append to or set the LATERAL expressions. 2143 2144 Example: 2145 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2146 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2147 2148 Args: 2149 *expressions (str | Expression): the SQL code strings to parse. 2150 If an `Expression` instance is passed, it will be used as-is. 2151 append (bool): if `True`, add to any existing expressions. 2152 Otherwise, this resets the expressions. 2153 dialect (str): the dialect used to parse the input expressions. 2154 copy (bool): if `False`, modify this expression instance in-place. 2155 opts (kwargs): other options to use to parse the input expressions. 2156 2157 Returns: 2158 Select: the modified expression. 2159 """ 2160 return _apply_list_builder( 2161 *expressions, 2162 instance=self, 2163 arg="laterals", 2164 append=append, 2165 into=Lateral, 2166 prefix="LATERAL VIEW", 2167 dialect=dialect, 2168 copy=copy, 2169 **opts, 2170 ) 2171 2172 def join( 2173 self, 2174 expression, 2175 on=None, 2176 using=None, 2177 append=True, 2178 join_type=None, 2179 join_alias=None, 2180 dialect=None, 2181 copy=True, 2182 **opts, 2183 ) -> Select: 2184 """ 2185 Append to or set the JOIN expressions. 2186 2187 Example: 2188 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2189 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2190 2191 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2192 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2193 2194 Use `join_type` to change the type of join: 2195 2196 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2197 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2198 2199 Args: 2200 expression (str | Expression): the SQL code string to parse. 2201 If an `Expression` instance is passed, it will be used as-is. 2202 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2203 If an `Expression` instance is passed, it will be used as-is. 2204 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2205 If an `Expression` instance is passed, it will be used as-is. 2206 append (bool): if `True`, add to any existing expressions. 2207 Otherwise, this resets the expressions. 2208 join_type (str): If set, alter the parsed join type 2209 dialect (str): the dialect used to parse the input expressions. 2210 copy (bool): if `False`, modify this expression instance in-place. 2211 opts (kwargs): other options to use to parse the input expressions. 2212 2213 Returns: 2214 Select: the modified expression. 2215 """ 2216 parse_args = {"dialect": dialect, **opts} 2217 2218 try: 2219 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2220 except ParseError: 2221 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2222 2223 join = expression if isinstance(expression, Join) else Join(this=expression) 2224 2225 if isinstance(join.this, Select): 2226 join.this.replace(join.this.subquery()) 2227 2228 if join_type: 2229 natural: t.Optional[Token] 2230 side: t.Optional[Token] 2231 kind: t.Optional[Token] 2232 2233 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2234 2235 if natural: 2236 join.set("natural", True) 2237 if side: 2238 join.set("side", side.text) 2239 if kind: 2240 join.set("kind", kind.text) 2241 2242 if on: 2243 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2244 join.set("on", on) 2245 2246 if using: 2247 join = _apply_list_builder( 2248 *ensure_collection(using), 2249 instance=join, 2250 arg="using", 2251 append=append, 2252 copy=copy, 2253 **opts, 2254 ) 2255 2256 if join_alias: 2257 join.set("this", alias_(join.this, join_alias, table=True)) 2258 return _apply_list_builder( 2259 join, 2260 instance=self, 2261 arg="joins", 2262 append=append, 2263 copy=copy, 2264 **opts, 2265 ) 2266 2267 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2268 """ 2269 Append to or set the WHERE expressions. 2270 2271 Example: 2272 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2273 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2274 2275 Args: 2276 *expressions (str | Expression): the SQL code strings to parse. 2277 If an `Expression` instance is passed, it will be used as-is. 2278 Multiple expressions are combined with an AND operator. 2279 append (bool): if `True`, AND the new expressions to any existing expression. 2280 Otherwise, this resets the expression. 2281 dialect (str): the dialect used to parse the input expressions. 2282 copy (bool): if `False`, modify this expression instance in-place. 2283 opts (kwargs): other options to use to parse the input expressions. 2284 2285 Returns: 2286 Select: the modified expression. 2287 """ 2288 return _apply_conjunction_builder( 2289 *expressions, 2290 instance=self, 2291 arg="where", 2292 append=append, 2293 into=Where, 2294 dialect=dialect, 2295 copy=copy, 2296 **opts, 2297 ) 2298 2299 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2300 """ 2301 Append to or set the HAVING expressions. 2302 2303 Example: 2304 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2305 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2306 2307 Args: 2308 *expressions (str | Expression): the SQL code strings to parse. 2309 If an `Expression` instance is passed, it will be used as-is. 2310 Multiple expressions are combined with an AND operator. 2311 append (bool): if `True`, AND the new expressions to any existing expression. 2312 Otherwise, this resets the expression. 2313 dialect (str): the dialect used to parse the input expressions. 2314 copy (bool): if `False`, modify this expression instance in-place. 2315 opts (kwargs): other options to use to parse the input expressions. 2316 2317 Returns: 2318 Select: the modified expression. 2319 """ 2320 return _apply_conjunction_builder( 2321 *expressions, 2322 instance=self, 2323 arg="having", 2324 append=append, 2325 into=Having, 2326 dialect=dialect, 2327 copy=copy, 2328 **opts, 2329 ) 2330 2331 def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2332 return _apply_list_builder( 2333 *expressions, 2334 instance=self, 2335 arg="windows", 2336 append=append, 2337 into=Window, 2338 dialect=dialect, 2339 copy=copy, 2340 **opts, 2341 ) 2342 2343 def distinct(self, distinct=True, copy=True) -> Select: 2344 """ 2345 Set the OFFSET expression. 2346 2347 Example: 2348 >>> Select().from_("tbl").select("x").distinct().sql() 2349 'SELECT DISTINCT x FROM tbl' 2350 2351 Args: 2352 distinct (bool): whether the Select should be distinct 2353 copy (bool): if `False`, modify this expression instance in-place. 2354 2355 Returns: 2356 Select: the modified expression. 2357 """ 2358 instance = _maybe_copy(self, copy) 2359 instance.set("distinct", Distinct() if distinct else None) 2360 return instance 2361 2362 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2363 """ 2364 Convert this expression to a CREATE TABLE AS statement. 2365 2366 Example: 2367 >>> Select().select("*").from_("tbl").ctas("x").sql() 2368 'CREATE TABLE x AS SELECT * FROM tbl' 2369 2370 Args: 2371 table (str | Expression): the SQL code string to parse as the table name. 2372 If another `Expression` instance is passed, it will be used as-is. 2373 properties (dict): an optional mapping of table properties 2374 dialect (str): the dialect used to parse the input table. 2375 copy (bool): if `False`, modify this expression instance in-place. 2376 opts (kwargs): other options to use to parse the input table. 2377 2378 Returns: 2379 Create: the CREATE TABLE AS expression 2380 """ 2381 instance = _maybe_copy(self, copy) 2382 table_expression = maybe_parse( 2383 table, 2384 into=Table, 2385 dialect=dialect, 2386 **opts, 2387 ) 2388 properties_expression = None 2389 if properties: 2390 properties_expression = Properties.from_dict(properties) 2391 2392 return Create( 2393 this=table_expression, 2394 kind="table", 2395 expression=instance, 2396 properties=properties_expression, 2397 ) 2398 2399 def lock(self, update: bool = True, copy: bool = True) -> Select: 2400 """ 2401 Set the locking read mode for this expression. 2402 2403 Examples: 2404 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2405 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2406 2407 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2408 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2409 2410 Args: 2411 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2412 copy: if `False`, modify this expression instance in-place. 2413 2414 Returns: 2415 The modified expression. 2416 """ 2417 2418 inst = _maybe_copy(self, copy) 2419 inst.set("lock", Lock(update=update)) 2420 2421 return inst 2422 2423 @property 2424 def named_selects(self) -> t.List[str]: 2425 return [e.output_name for e in self.expressions if e.alias_or_name] 2426 2427 @property 2428 def selects(self) -> t.List[Expression]: 2429 return self.expressions 2430 2431 2432class Subquery(DerivedTable, Unionable): 2433 arg_types = { 2434 "this": True, 2435 "alias": False, 2436 "with": False, 2437 **QUERY_MODIFIERS, 2438 } 2439 2440 def unnest(self): 2441 """ 2442 Returns the first non subquery. 2443 """ 2444 expression = self 2445 while isinstance(expression, Subquery): 2446 expression = expression.this 2447 return expression 2448 2449 @property 2450 def output_name(self): 2451 return self.alias 2452 2453 2454class TableSample(Expression): 2455 arg_types = { 2456 "this": False, 2457 "method": False, 2458 "bucket_numerator": False, 2459 "bucket_denominator": False, 2460 "bucket_field": False, 2461 "percent": False, 2462 "rows": False, 2463 "size": False, 2464 "seed": False, 2465 } 2466 2467 2468class Tag(Expression): 2469 """Tags are used for generating arbitrary sql like SELECT <span>x</span>.""" 2470 2471 arg_types = { 2472 "this": False, 2473 "prefix": False, 2474 "postfix": False, 2475 } 2476 2477 2478class Pivot(Expression): 2479 arg_types = { 2480 "this": False, 2481 "expressions": True, 2482 "field": True, 2483 "unpivot": True, 2484 } 2485 2486 2487class Window(Expression): 2488 arg_types = { 2489 "this": True, 2490 "partition_by": False, 2491 "order": False, 2492 "spec": False, 2493 "alias": False, 2494 } 2495 2496 2497class WindowSpec(Expression): 2498 arg_types = { 2499 "kind": False, 2500 "start": False, 2501 "start_side": False, 2502 "end": False, 2503 "end_side": False, 2504 } 2505 2506 2507class Where(Expression): 2508 pass 2509 2510 2511class Star(Expression): 2512 arg_types = {"except": False, "replace": False} 2513 2514 @property 2515 def name(self) -> str: 2516 return "*" 2517 2518 @property 2519 def output_name(self): 2520 return self.name 2521 2522 2523class Parameter(Expression): 2524 arg_types = {"this": True, "wrapped": False} 2525 2526 2527class SessionParameter(Expression): 2528 arg_types = {"this": True, "kind": False} 2529 2530 2531class Placeholder(Expression): 2532 arg_types = {"this": False} 2533 2534 2535class Null(Condition): 2536 arg_types: t.Dict[str, t.Any] = {} 2537 2538 @property 2539 def name(self) -> str: 2540 return "NULL" 2541 2542 2543class Boolean(Condition): 2544 pass 2545 2546 2547class DataType(Expression): 2548 arg_types = { 2549 "this": True, 2550 "expressions": False, 2551 "nested": False, 2552 "values": False, 2553 "prefix": False, 2554 } 2555 2556 class Type(AutoName): 2557 CHAR = auto() 2558 NCHAR = auto() 2559 VARCHAR = auto() 2560 NVARCHAR = auto() 2561 TEXT = auto() 2562 MEDIUMTEXT = auto() 2563 LONGTEXT = auto() 2564 MEDIUMBLOB = auto() 2565 LONGBLOB = auto() 2566 BINARY = auto() 2567 VARBINARY = auto() 2568 INT = auto() 2569 TINYINT = auto() 2570 SMALLINT = auto() 2571 BIGINT = auto() 2572 FLOAT = auto() 2573 DOUBLE = auto() 2574 DECIMAL = auto() 2575 BOOLEAN = auto() 2576 JSON = auto() 2577 JSONB = auto() 2578 INTERVAL = auto() 2579 TIME = auto() 2580 TIMESTAMP = auto() 2581 TIMESTAMPTZ = auto() 2582 TIMESTAMPLTZ = auto() 2583 DATE = auto() 2584 DATETIME = auto() 2585 ARRAY = auto() 2586 MAP = auto() 2587 UUID = auto() 2588 GEOGRAPHY = auto() 2589 GEOMETRY = auto() 2590 STRUCT = auto() 2591 NULLABLE = auto() 2592 HLLSKETCH = auto() 2593 HSTORE = auto() 2594 SUPER = auto() 2595 SERIAL = auto() 2596 SMALLSERIAL = auto() 2597 BIGSERIAL = auto() 2598 XML = auto() 2599 UNIQUEIDENTIFIER = auto() 2600 MONEY = auto() 2601 SMALLMONEY = auto() 2602 ROWVERSION = auto() 2603 IMAGE = auto() 2604 VARIANT = auto() 2605 OBJECT = auto() 2606 NULL = auto() 2607 UNKNOWN = auto() # Sentinel value, useful for type annotation 2608 2609 TEXT_TYPES = { 2610 Type.CHAR, 2611 Type.NCHAR, 2612 Type.VARCHAR, 2613 Type.NVARCHAR, 2614 Type.TEXT, 2615 } 2616 2617 INTEGER_TYPES = { 2618 Type.INT, 2619 Type.TINYINT, 2620 Type.SMALLINT, 2621 Type.BIGINT, 2622 } 2623 2624 FLOAT_TYPES = { 2625 Type.FLOAT, 2626 Type.DOUBLE, 2627 } 2628 2629 NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES} 2630 2631 TEMPORAL_TYPES = { 2632 Type.TIMESTAMP, 2633 Type.TIMESTAMPTZ, 2634 Type.TIMESTAMPLTZ, 2635 Type.DATE, 2636 Type.DATETIME, 2637 } 2638 2639 @classmethod 2640 def build( 2641 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2642 ) -> DataType: 2643 from sqlglot import parse_one 2644 2645 if isinstance(dtype, str): 2646 if dtype.upper() in cls.Type.__members__: 2647 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2648 else: 2649 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2650 if data_type_exp is None: 2651 raise ValueError(f"Unparsable data type value: {dtype}") 2652 elif isinstance(dtype, DataType.Type): 2653 data_type_exp = DataType(this=dtype) 2654 elif isinstance(dtype, DataType): 2655 return dtype 2656 else: 2657 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2658 return DataType(**{**data_type_exp.args, **kwargs}) 2659 2660 def is_type(self, dtype: DataType.Type) -> bool: 2661 return self.this == dtype 2662 2663 2664# https://www.postgresql.org/docs/15/datatype-pseudo.html 2665class PseudoType(Expression): 2666 pass 2667 2668 2669class StructKwarg(Expression): 2670 arg_types = {"this": True, "expression": True} 2671 2672 2673# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...) 2674class SubqueryPredicate(Predicate): 2675 pass 2676 2677 2678class All(SubqueryPredicate): 2679 pass 2680 2681 2682class Any(SubqueryPredicate): 2683 pass 2684 2685 2686class Exists(SubqueryPredicate): 2687 pass 2688 2689 2690# Commands to interact with the databases or engines. For most of the command 2691# expressions we parse whatever comes after the command's name as a string. 2692class Command(Expression): 2693 arg_types = {"this": True, "expression": False} 2694 2695 2696class Transaction(Expression): 2697 arg_types = {"this": False, "modes": False} 2698 2699 2700class Commit(Expression): 2701 arg_types = {"chain": False} 2702 2703 2704class Rollback(Expression): 2705 arg_types = {"savepoint": False} 2706 2707 2708class AlterTable(Expression): 2709 arg_types = {"this": True, "actions": True, "exists": False} 2710 2711 2712class AddConstraint(Expression): 2713 arg_types = {"this": False, "expression": False, "enforced": False} 2714 2715 2716class DropPartition(Expression): 2717 arg_types = {"expressions": True, "exists": False} 2718 2719 2720# Binary expressions like (ADD a b) 2721class Binary(Expression): 2722 arg_types = {"this": True, "expression": True} 2723 2724 @property 2725 def left(self): 2726 return self.this 2727 2728 @property 2729 def right(self): 2730 return self.expression 2731 2732 2733class Add(Binary): 2734 pass 2735 2736 2737class Connector(Binary, Condition): 2738 pass 2739 2740 2741class And(Connector): 2742 pass 2743 2744 2745class Or(Connector): 2746 pass 2747 2748 2749class BitwiseAnd(Binary): 2750 pass 2751 2752 2753class BitwiseLeftShift(Binary): 2754 pass 2755 2756 2757class BitwiseOr(Binary): 2758 pass 2759 2760 2761class BitwiseRightShift(Binary): 2762 pass 2763 2764 2765class BitwiseXor(Binary): 2766 pass 2767 2768 2769class Div(Binary): 2770 pass 2771 2772 2773class Dot(Binary): 2774 @property 2775 def name(self) -> str: 2776 return self.expression.name 2777 2778 2779class DPipe(Binary): 2780 pass 2781 2782 2783class EQ(Binary, Predicate): 2784 pass 2785 2786 2787class NullSafeEQ(Binary, Predicate): 2788 pass 2789 2790 2791class NullSafeNEQ(Binary, Predicate): 2792 pass 2793 2794 2795class Distance(Binary): 2796 pass 2797 2798 2799class Escape(Binary): 2800 pass 2801 2802 2803class Glob(Binary, Predicate): 2804 pass 2805 2806 2807class GT(Binary, Predicate): 2808 pass 2809 2810 2811class GTE(Binary, Predicate): 2812 pass 2813 2814 2815class ILike(Binary, Predicate): 2816 pass 2817 2818 2819class ILikeAny(Binary, Predicate): 2820 pass 2821 2822 2823class IntDiv(Binary): 2824 pass 2825 2826 2827class Is(Binary, Predicate): 2828 pass 2829 2830 2831class Kwarg(Binary): 2832 """Kwarg in special functions like func(kwarg => y).""" 2833 2834 2835class Like(Binary, Predicate): 2836 pass 2837 2838 2839class LikeAny(Binary, Predicate): 2840 pass 2841 2842 2843class LT(Binary, Predicate): 2844 pass 2845 2846 2847class LTE(Binary, Predicate): 2848 pass 2849 2850 2851class Mod(Binary): 2852 pass 2853 2854 2855class Mul(Binary): 2856 pass 2857 2858 2859class NEQ(Binary, Predicate): 2860 pass 2861 2862 2863class SimilarTo(Binary, Predicate): 2864 pass 2865 2866 2867class Slice(Binary): 2868 arg_types = {"this": False, "expression": False} 2869 2870 2871class Sub(Binary): 2872 pass 2873 2874 2875# Unary Expressions 2876# (NOT a) 2877class Unary(Expression): 2878 pass 2879 2880 2881class BitwiseNot(Unary): 2882 pass 2883 2884 2885class Not(Unary, Condition): 2886 pass 2887 2888 2889class Paren(Unary, Condition): 2890 arg_types = {"this": True, "with": False} 2891 2892 2893class Neg(Unary): 2894 pass 2895 2896 2897# Special Functions 2898class Alias(Expression): 2899 arg_types = {"this": True, "alias": False} 2900 2901 @property 2902 def output_name(self): 2903 return self.alias 2904 2905 2906class Aliases(Expression): 2907 arg_types = {"this": True, "expressions": True} 2908 2909 @property 2910 def aliases(self): 2911 return self.expressions 2912 2913 2914class AtTimeZone(Expression): 2915 arg_types = {"this": True, "zone": True} 2916 2917 2918class Between(Predicate): 2919 arg_types = {"this": True, "low": True, "high": True} 2920 2921 2922class Bracket(Condition): 2923 arg_types = {"this": True, "expressions": True} 2924 2925 2926class Distinct(Expression): 2927 arg_types = {"expressions": False, "on": False} 2928 2929 2930class In(Predicate): 2931 arg_types = { 2932 "this": True, 2933 "expressions": False, 2934 "query": False, 2935 "unnest": False, 2936 "field": False, 2937 "is_global": False, 2938 } 2939 2940 2941class TimeUnit(Expression): 2942 """Automatically converts unit arg into a var.""" 2943 2944 arg_types = {"unit": False} 2945 2946 def __init__(self, **args): 2947 unit = args.get("unit") 2948 if isinstance(unit, Column): 2949 args["unit"] = Var(this=unit.name) 2950 elif isinstance(unit, Week): 2951 unit.set("this", Var(this=unit.this.name)) 2952 super().__init__(**args) 2953 2954 2955class Interval(TimeUnit): 2956 arg_types = {"this": False, "unit": False} 2957 2958 2959class IgnoreNulls(Expression): 2960 pass 2961 2962 2963class RespectNulls(Expression): 2964 pass 2965 2966 2967# Functions 2968class Func(Condition): 2969 """ 2970 The base class for all function expressions. 2971 2972 Attributes: 2973 is_var_len_args (bool): if set to True the last argument defined in arg_types will be 2974 treated as a variable length argument and the argument's value will be stored as a list. 2975 _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) 2976 for this function expression. These values are used to map this node to a name during parsing 2977 as well as to provide the function's name during SQL string generation. By default the SQL 2978 name is set to the expression's class name transformed to snake case. 2979 """ 2980 2981 is_var_len_args = False 2982 2983 @classmethod 2984 def from_arg_list(cls, args): 2985 if cls.is_var_len_args: 2986 all_arg_keys = list(cls.arg_types) 2987 # If this function supports variable length argument treat the last argument as such. 2988 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 2989 num_non_var = len(non_var_len_arg_keys) 2990 2991 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 2992 args_dict[all_arg_keys[-1]] = args[num_non_var:] 2993 else: 2994 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 2995 2996 return cls(**args_dict) 2997 2998 @classmethod 2999 def sql_names(cls): 3000 if cls is Func: 3001 raise NotImplementedError( 3002 "SQL name is only supported by concrete function implementations" 3003 ) 3004 if "_sql_names" not in cls.__dict__: 3005 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3006 return cls._sql_names 3007 3008 @classmethod 3009 def sql_name(cls): 3010 return cls.sql_names()[0] 3011 3012 @classmethod 3013 def default_parser_mappings(cls): 3014 return {name: cls.from_arg_list for name in cls.sql_names()} 3015 3016 3017class AggFunc(Func): 3018 pass 3019 3020 3021class Abs(Func): 3022 pass 3023 3024 3025class Anonymous(Func): 3026 arg_types = {"this": True, "expressions": False} 3027 is_var_len_args = True 3028 3029 3030class ApproxDistinct(AggFunc): 3031 arg_types = {"this": True, "accuracy": False} 3032 3033 3034class Array(Func): 3035 arg_types = {"expressions": False} 3036 is_var_len_args = True 3037 3038 3039class GenerateSeries(Func): 3040 arg_types = {"start": True, "end": True, "step": False} 3041 3042 3043class ArrayAgg(AggFunc): 3044 pass 3045 3046 3047class ArrayAll(Func): 3048 arg_types = {"this": True, "expression": True} 3049 3050 3051class ArrayAny(Func): 3052 arg_types = {"this": True, "expression": True} 3053 3054 3055class ArrayConcat(Func): 3056 arg_types = {"this": True, "expressions": False} 3057 is_var_len_args = True 3058 3059 3060class ArrayContains(Func): 3061 arg_types = {"this": True, "expression": True} 3062 3063 3064class ArrayFilter(Func): 3065 arg_types = {"this": True, "expression": True} 3066 _sql_names = ["FILTER", "ARRAY_FILTER"] 3067 3068 3069class ArraySize(Func): 3070 arg_types = {"this": True, "expression": False} 3071 3072 3073class ArraySort(Func): 3074 arg_types = {"this": True, "expression": False} 3075 3076 3077class ArraySum(Func): 3078 pass 3079 3080 3081class ArrayUnionAgg(AggFunc): 3082 pass 3083 3084 3085class Avg(AggFunc): 3086 pass 3087 3088 3089class AnyValue(AggFunc): 3090 pass 3091 3092 3093class Case(Func): 3094 arg_types = {"this": False, "ifs": True, "default": False} 3095 3096 3097class Cast(Func): 3098 arg_types = {"this": True, "to": True} 3099 3100 @property 3101 def name(self) -> str: 3102 return self.this.name 3103 3104 @property 3105 def to(self): 3106 return self.args["to"] 3107 3108 @property 3109 def output_name(self): 3110 return self.name 3111 3112 def is_type(self, dtype: DataType.Type) -> bool: 3113 return self.to.is_type(dtype) 3114 3115 3116class Collate(Binary): 3117 pass 3118 3119 3120class TryCast(Cast): 3121 pass 3122 3123 3124class Ceil(Func): 3125 arg_types = {"this": True, "decimals": False} 3126 _sql_names = ["CEIL", "CEILING"] 3127 3128 3129class Coalesce(Func): 3130 arg_types = {"this": True, "expressions": False} 3131 is_var_len_args = True 3132 3133 3134class Concat(Func): 3135 arg_types = {"expressions": True} 3136 is_var_len_args = True 3137 3138 3139class ConcatWs(Concat): 3140 _sql_names = ["CONCAT_WS"] 3141 3142 3143class Count(AggFunc): 3144 arg_types = {"this": False} 3145 3146 3147class CurrentDate(Func): 3148 arg_types = {"this": False} 3149 3150 3151class CurrentDatetime(Func): 3152 arg_types = {"this": False} 3153 3154 3155class CurrentTime(Func): 3156 arg_types = {"this": False} 3157 3158 3159class CurrentTimestamp(Func): 3160 arg_types = {"this": False} 3161 3162 3163class DateAdd(Func, TimeUnit): 3164 arg_types = {"this": True, "expression": True, "unit": False} 3165 3166 3167class DateSub(Func, TimeUnit): 3168 arg_types = {"this": True, "expression": True, "unit": False} 3169 3170 3171class DateDiff(Func, TimeUnit): 3172 arg_types = {"this": True, "expression": True, "unit": False} 3173 3174 3175class DateTrunc(Func): 3176 arg_types = {"unit": True, "this": True, "zone": False} 3177 3178 3179class DatetimeAdd(Func, TimeUnit): 3180 arg_types = {"this": True, "expression": True, "unit": False} 3181 3182 3183class DatetimeSub(Func, TimeUnit): 3184 arg_types = {"this": True, "expression": True, "unit": False} 3185 3186 3187class DatetimeDiff(Func, TimeUnit): 3188 arg_types = {"this": True, "expression": True, "unit": False} 3189 3190 3191class DatetimeTrunc(Func, TimeUnit): 3192 arg_types = {"this": True, "unit": True, "zone": False} 3193 3194 3195class DayOfWeek(Func): 3196 _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"] 3197 3198 3199class DayOfMonth(Func): 3200 _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"] 3201 3202 3203class DayOfYear(Func): 3204 _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"] 3205 3206 3207class WeekOfYear(Func): 3208 _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"] 3209 3210 3211class LastDateOfMonth(Func): 3212 pass 3213 3214 3215class Extract(Func): 3216 arg_types = {"this": True, "expression": True} 3217 3218 3219class TimestampAdd(Func, TimeUnit): 3220 arg_types = {"this": True, "expression": True, "unit": False} 3221 3222 3223class TimestampSub(Func, TimeUnit): 3224 arg_types = {"this": True, "expression": True, "unit": False} 3225 3226 3227class TimestampDiff(Func, TimeUnit): 3228 arg_types = {"this": True, "expression": True, "unit": False} 3229 3230 3231class TimestampTrunc(Func, TimeUnit): 3232 arg_types = {"this": True, "unit": True, "zone": False} 3233 3234 3235class TimeAdd(Func, TimeUnit): 3236 arg_types = {"this": True, "expression": True, "unit": False} 3237 3238 3239class TimeSub(Func, TimeUnit): 3240 arg_types = {"this": True, "expression": True, "unit": False} 3241 3242 3243class TimeDiff(Func, TimeUnit): 3244 arg_types = {"this": True, "expression": True, "unit": False} 3245 3246 3247class TimeTrunc(Func, TimeUnit): 3248 arg_types = {"this": True, "unit": True, "zone": False} 3249 3250 3251class DateFromParts(Func): 3252 _sql_names = ["DATEFROMPARTS"] 3253 arg_types = {"year": True, "month": True, "day": True} 3254 3255 3256class DateStrToDate(Func): 3257 pass 3258 3259 3260class DateToDateStr(Func): 3261 pass 3262 3263 3264class DateToDi(Func): 3265 pass 3266 3267 3268class Day(Func): 3269 pass 3270 3271 3272class Decode(Func): 3273 arg_types = {"this": True, "charset": True, "replace": False} 3274 3275 3276class DiToDate(Func): 3277 pass 3278 3279 3280class Encode(Func): 3281 arg_types = {"this": True, "charset": True} 3282 3283 3284class Exp(Func): 3285 pass 3286 3287 3288class Explode(Func): 3289 pass 3290 3291 3292class Floor(Func): 3293 arg_types = {"this": True, "decimals": False} 3294 3295 3296class Greatest(Func): 3297 arg_types = {"this": True, "expressions": False} 3298 is_var_len_args = True 3299 3300 3301class GroupConcat(Func): 3302 arg_types = {"this": True, "separator": False} 3303 3304 3305class Hex(Func): 3306 pass 3307 3308 3309class If(Func): 3310 arg_types = {"this": True, "true": True, "false": False} 3311 3312 3313class IfNull(Func): 3314 arg_types = {"this": True, "expression": False} 3315 _sql_names = ["IFNULL", "NVL"] 3316 3317 3318class Initcap(Func): 3319 pass 3320 3321 3322class JSONBContains(Binary): 3323 _sql_names = ["JSONB_CONTAINS"] 3324 3325 3326class JSONExtract(Binary, Func): 3327 _sql_names = ["JSON_EXTRACT"] 3328 3329 3330class JSONExtractScalar(JSONExtract): 3331 _sql_names = ["JSON_EXTRACT_SCALAR"] 3332 3333 3334class JSONBExtract(JSONExtract): 3335 _sql_names = ["JSONB_EXTRACT"] 3336 3337 3338class JSONBExtractScalar(JSONExtract): 3339 _sql_names = ["JSONB_EXTRACT_SCALAR"] 3340 3341 3342class Least(Func): 3343 arg_types = {"this": True, "expressions": False} 3344 is_var_len_args = True 3345 3346 3347class Length(Func): 3348 pass 3349 3350 3351class Levenshtein(Func): 3352 arg_types = { 3353 "this": True, 3354 "expression": False, 3355 "ins_cost": False, 3356 "del_cost": False, 3357 "sub_cost": False, 3358 } 3359 3360 3361class Ln(Func): 3362 pass 3363 3364 3365class Log(Func): 3366 arg_types = {"this": True, "expression": False} 3367 3368 3369class Log2(Func): 3370 pass 3371 3372 3373class Log10(Func): 3374 pass 3375 3376 3377class LogicalOr(AggFunc): 3378 _sql_names = ["LOGICAL_OR", "BOOL_OR"] 3379 3380 3381class Lower(Func): 3382 _sql_names = ["LOWER", "LCASE"] 3383 3384 3385class Map(Func): 3386 arg_types = {"keys": False, "values": False} 3387 3388 3389class VarMap(Func): 3390 arg_types = {"keys": True, "values": True} 3391 is_var_len_args = True 3392 3393 3394class Matches(Func): 3395 """Oracle/Snowflake decode. 3396 https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm 3397 Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else) 3398 """ 3399 3400 arg_types = {"this": True, "expressions": True} 3401 is_var_len_args = True 3402 3403 3404class Max(AggFunc): 3405 arg_types = {"this": True, "expression": False} 3406 3407 3408class Min(AggFunc): 3409 arg_types = {"this": True, "expression": False} 3410 3411 3412class Month(Func): 3413 pass 3414 3415 3416class Nvl2(Func): 3417 arg_types = {"this": True, "true": True, "false": False} 3418 3419 3420class Posexplode(Func): 3421 pass 3422 3423 3424class Pow(Binary, Func): 3425 _sql_names = ["POWER", "POW"] 3426 3427 3428class PercentileCont(AggFunc): 3429 pass 3430 3431 3432class PercentileDisc(AggFunc): 3433 pass 3434 3435 3436class Quantile(AggFunc): 3437 arg_types = {"this": True, "quantile": True} 3438 3439 3440# Clickhouse-specific: 3441# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/quantiles/#quantiles 3442class Quantiles(AggFunc): 3443 arg_types = {"parameters": True, "expressions": True} 3444 3445 3446class QuantileIf(AggFunc): 3447 arg_types = {"parameters": True, "expressions": True} 3448 3449 3450class ApproxQuantile(Quantile): 3451 arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False} 3452 3453 3454class ReadCSV(Func): 3455 _sql_names = ["READ_CSV"] 3456 is_var_len_args = True 3457 arg_types = {"this": True, "expressions": False} 3458 3459 3460class Reduce(Func): 3461 arg_types = {"this": True, "initial": True, "merge": True, "finish": False} 3462 3463 3464class RegexpExtract(Func): 3465 arg_types = { 3466 "this": True, 3467 "expression": True, 3468 "position": False, 3469 "occurrence": False, 3470 "group": False, 3471 } 3472 3473 3474class RegexpLike(Func): 3475 arg_types = {"this": True, "expression": True, "flag": False} 3476 3477 3478class RegexpILike(Func): 3479 arg_types = {"this": True, "expression": True, "flag": False} 3480 3481 3482class RegexpSplit(Func): 3483 arg_types = {"this": True, "expression": True} 3484 3485 3486class Repeat(Func): 3487 arg_types = {"this": True, "times": True} 3488 3489 3490class Round(Func): 3491 arg_types = {"this": True, "decimals": False} 3492 3493 3494class RowNumber(Func): 3495 arg_types: t.Dict[str, t.Any] = {} 3496 3497 3498class SafeDivide(Func): 3499 arg_types = {"this": True, "expression": True} 3500 3501 3502class SetAgg(AggFunc): 3503 pass 3504 3505 3506class SortArray(Func): 3507 arg_types = {"this": True, "asc": False} 3508 3509 3510class Split(Func): 3511 arg_types = {"this": True, "expression": True, "limit": False} 3512 3513 3514# Start may be omitted in the case of postgres 3515# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6 3516class Substring(Func): 3517 arg_types = {"this": True, "start": False, "length": False} 3518 3519 3520class StrPosition(Func): 3521 arg_types = { 3522 "this": True, 3523 "substr": True, 3524 "position": False, 3525 "instance": False, 3526 } 3527 3528 3529class StrToDate(Func): 3530 arg_types = {"this": True, "format": True} 3531 3532 3533class StrToTime(Func): 3534 arg_types = {"this": True, "format": True} 3535 3536 3537# Spark allows unix_timestamp() 3538# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html 3539class StrToUnix(Func): 3540 arg_types = {"this": False, "format": False} 3541 3542 3543class NumberToStr(Func): 3544 arg_types = {"this": True, "format": True} 3545 3546 3547class Struct(Func): 3548 arg_types = {"expressions": True} 3549 is_var_len_args = True 3550 3551 3552class StructExtract(Func): 3553 arg_types = {"this": True, "expression": True} 3554 3555 3556class Sum(AggFunc): 3557 pass 3558 3559 3560class Sqrt(Func): 3561 pass 3562 3563 3564class Stddev(AggFunc): 3565 pass 3566 3567 3568class StddevPop(AggFunc): 3569 pass 3570 3571 3572class StddevSamp(AggFunc): 3573 pass 3574 3575 3576class TimeToStr(Func): 3577 arg_types = {"this": True, "format": True} 3578 3579 3580class TimeToTimeStr(Func): 3581 pass 3582 3583 3584class TimeToUnix(Func): 3585 pass 3586 3587 3588class TimeStrToDate(Func): 3589 pass 3590 3591 3592class TimeStrToTime(Func): 3593 pass 3594 3595 3596class TimeStrToUnix(Func): 3597 pass 3598 3599 3600class Trim(Func): 3601 arg_types = { 3602 "this": True, 3603 "expression": False, 3604 "position": False, 3605 "collation": False, 3606 } 3607 3608 3609class TsOrDsAdd(Func, TimeUnit): 3610 arg_types = {"this": True, "expression": True, "unit": False} 3611 3612 3613class TsOrDsToDateStr(Func): 3614 pass 3615 3616 3617class TsOrDsToDate(Func): 3618 arg_types = {"this": True, "format": False} 3619 3620 3621class TsOrDiToDi(Func): 3622 pass 3623 3624 3625class Unhex(Func): 3626 pass 3627 3628 3629class UnixToStr(Func): 3630 arg_types = {"this": True, "format": False} 3631 3632 3633# https://prestodb.io/docs/current/functions/datetime.html 3634# presto has weird zone/hours/minutes 3635class UnixToTime(Func): 3636 arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False} 3637 3638 SECONDS = Literal.string("seconds") 3639 MILLIS = Literal.string("millis") 3640 MICROS = Literal.string("micros") 3641 3642 3643class UnixToTimeStr(Func): 3644 pass 3645 3646 3647class Upper(Func): 3648 _sql_names = ["UPPER", "UCASE"] 3649 3650 3651class Variance(AggFunc): 3652 _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"] 3653 3654 3655class VariancePop(AggFunc): 3656 _sql_names = ["VARIANCE_POP", "VAR_POP"] 3657 3658 3659class Week(Func): 3660 arg_types = {"this": True, "mode": False} 3661 3662 3663class XMLTable(Func): 3664 arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False} 3665 3666 3667class Year(Func): 3668 pass 3669 3670 3671class Use(Expression): 3672 arg_types = {"this": True, "kind": False} 3673 3674 3675class Merge(Expression): 3676 arg_types = {"this": True, "using": True, "on": True, "expressions": True} 3677 3678 3679class When(Func): 3680 arg_types = {"this": True, "then": True} 3681 3682 3683def _norm_args(expression): 3684 args = {} 3685 3686 for k, arg in expression.args.items(): 3687 if isinstance(arg, list): 3688 arg = [_norm_arg(a) for a in arg] 3689 if not arg: 3690 arg = None 3691 else: 3692 arg = _norm_arg(arg) 3693 3694 if arg is not None and arg is not False: 3695 args[k] = arg 3696 3697 return args 3698 3699 3700def _norm_arg(arg): 3701 return arg.lower() if isinstance(arg, str) else arg 3702 3703 3704ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func)) 3705 3706 3707# Helpers 3708def maybe_parse( 3709 sql_or_expression: str | Expression, 3710 *, 3711 into: t.Optional[IntoType] = None, 3712 dialect: DialectType = None, 3713 prefix: t.Optional[str] = None, 3714 copy: bool = False, 3715 **opts, 3716) -> Expression: 3717 """Gracefully handle a possible string or expression. 3718 3719 Example: 3720 >>> maybe_parse("1") 3721 (LITERAL this: 1, is_string: False) 3722 >>> maybe_parse(to_identifier("x")) 3723 (IDENTIFIER this: x, quoted: False) 3724 3725 Args: 3726 sql_or_expression: the SQL code string or an expression 3727 into: the SQLGlot Expression to parse into 3728 dialect: the dialect used to parse the input expressions (in the case that an 3729 input expression is a SQL string). 3730 prefix: a string to prefix the sql with before it gets parsed 3731 (automatically includes a space) 3732 copy: whether or not to copy the expression. 3733 **opts: other options to use to parse the input expressions (again, in the case 3734 that an input expression is a SQL string). 3735 3736 Returns: 3737 Expression: the parsed or given expression. 3738 """ 3739 if isinstance(sql_or_expression, Expression): 3740 if copy: 3741 return sql_or_expression.copy() 3742 return sql_or_expression 3743 3744 import sqlglot 3745 3746 sql = str(sql_or_expression) 3747 if prefix: 3748 sql = f"{prefix} {sql}" 3749 return sqlglot.parse_one(sql, read=dialect, into=into, **opts) 3750 3751 3752def _maybe_copy(instance, copy=True): 3753 return instance.copy() if copy else instance 3754 3755 3756def _is_wrong_expression(expression, into): 3757 return isinstance(expression, Expression) and not isinstance(expression, into) 3758 3759 3760def _apply_builder( 3761 expression, 3762 instance, 3763 arg, 3764 copy=True, 3765 prefix=None, 3766 into=None, 3767 dialect=None, 3768 **opts, 3769): 3770 if _is_wrong_expression(expression, into): 3771 expression = into(this=expression) 3772 instance = _maybe_copy(instance, copy) 3773 expression = maybe_parse( 3774 sql_or_expression=expression, 3775 prefix=prefix, 3776 into=into, 3777 dialect=dialect, 3778 **opts, 3779 ) 3780 instance.set(arg, expression) 3781 return instance 3782 3783 3784def _apply_child_list_builder( 3785 *expressions, 3786 instance, 3787 arg, 3788 append=True, 3789 copy=True, 3790 prefix=None, 3791 into=None, 3792 dialect=None, 3793 properties=None, 3794 **opts, 3795): 3796 instance = _maybe_copy(instance, copy) 3797 parsed = [] 3798 for expression in expressions: 3799 if _is_wrong_expression(expression, into): 3800 expression = into(expressions=[expression]) 3801 expression = maybe_parse( 3802 expression, 3803 into=into, 3804 dialect=dialect, 3805 prefix=prefix, 3806 **opts, 3807 ) 3808 parsed.extend(expression.expressions) 3809 3810 existing = instance.args.get(arg) 3811 if append and existing: 3812 parsed = existing.expressions + parsed 3813 3814 child = into(expressions=parsed) 3815 for k, v in (properties or {}).items(): 3816 child.set(k, v) 3817 instance.set(arg, child) 3818 return instance 3819 3820 3821def _apply_list_builder( 3822 *expressions, 3823 instance, 3824 arg, 3825 append=True, 3826 copy=True, 3827 prefix=None, 3828 into=None, 3829 dialect=None, 3830 **opts, 3831): 3832 inst = _maybe_copy(instance, copy) 3833 3834 expressions = [ 3835 maybe_parse( 3836 sql_or_expression=expression, 3837 into=into, 3838 prefix=prefix, 3839 dialect=dialect, 3840 **opts, 3841 ) 3842 for expression in expressions 3843 ] 3844 3845 existing_expressions = inst.args.get(arg) 3846 if append and existing_expressions: 3847 expressions = existing_expressions + expressions 3848 3849 inst.set(arg, expressions) 3850 return inst 3851 3852 3853def _apply_conjunction_builder( 3854 *expressions, 3855 instance, 3856 arg, 3857 into=None, 3858 append=True, 3859 copy=True, 3860 dialect=None, 3861 **opts, 3862): 3863 expressions = [exp for exp in expressions if exp is not None and exp != ""] 3864 if not expressions: 3865 return instance 3866 3867 inst = _maybe_copy(instance, copy) 3868 3869 existing = inst.args.get(arg) 3870 if append and existing is not None: 3871 expressions = [existing.this if into else existing] + list(expressions) 3872 3873 node = and_(*expressions, dialect=dialect, **opts) 3874 3875 inst.set(arg, into(this=node) if into else node) 3876 return inst 3877 3878 3879def _combine(expressions, operator, dialect=None, **opts): 3880 expressions = [condition(expression, dialect=dialect, **opts) for expression in expressions] 3881 this = expressions[0] 3882 if expressions[1:]: 3883 this = _wrap_operator(this) 3884 for expression in expressions[1:]: 3885 this = operator(this=this, expression=_wrap_operator(expression)) 3886 return this 3887 3888 3889def _wrap_operator(expression): 3890 if isinstance(expression, (And, Or, Not)): 3891 expression = Paren(this=expression) 3892 return expression 3893 3894 3895def union(left, right, distinct=True, dialect=None, **opts): 3896 """ 3897 Initializes a syntax tree from one UNION expression. 3898 3899 Example: 3900 >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 3901 'SELECT * FROM foo UNION SELECT * FROM bla' 3902 3903 Args: 3904 left (str | Expression): the SQL code string corresponding to the left-hand side. 3905 If an `Expression` instance is passed, it will be used as-is. 3906 right (str | Expression): the SQL code string corresponding to the right-hand side. 3907 If an `Expression` instance is passed, it will be used as-is. 3908 distinct (bool): set the DISTINCT flag if and only if this is true. 3909 dialect (str): the dialect used to parse the input expression. 3910 opts (kwargs): other options to use to parse the input expressions. 3911 Returns: 3912 Union: the syntax tree for the UNION expression. 3913 """ 3914 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3915 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3916 3917 return Union(this=left, expression=right, distinct=distinct) 3918 3919 3920def intersect(left, right, distinct=True, dialect=None, **opts): 3921 """ 3922 Initializes a syntax tree from one INTERSECT expression. 3923 3924 Example: 3925 >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 3926 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 3927 3928 Args: 3929 left (str | Expression): the SQL code string corresponding to the left-hand side. 3930 If an `Expression` instance is passed, it will be used as-is. 3931 right (str | Expression): the SQL code string corresponding to the right-hand side. 3932 If an `Expression` instance is passed, it will be used as-is. 3933 distinct (bool): set the DISTINCT flag if and only if this is true. 3934 dialect (str): the dialect used to parse the input expression. 3935 opts (kwargs): other options to use to parse the input expressions. 3936 Returns: 3937 Intersect: the syntax tree for the INTERSECT expression. 3938 """ 3939 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3940 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3941 3942 return Intersect(this=left, expression=right, distinct=distinct) 3943 3944 3945def except_(left, right, distinct=True, dialect=None, **opts): 3946 """ 3947 Initializes a syntax tree from one EXCEPT expression. 3948 3949 Example: 3950 >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 3951 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 3952 3953 Args: 3954 left (str | Expression): the SQL code string corresponding to the left-hand side. 3955 If an `Expression` instance is passed, it will be used as-is. 3956 right (str | Expression): the SQL code string corresponding to the right-hand side. 3957 If an `Expression` instance is passed, it will be used as-is. 3958 distinct (bool): set the DISTINCT flag if and only if this is true. 3959 dialect (str): the dialect used to parse the input expression. 3960 opts (kwargs): other options to use to parse the input expressions. 3961 Returns: 3962 Except: the syntax tree for the EXCEPT statement. 3963 """ 3964 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3965 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3966 3967 return Except(this=left, expression=right, distinct=distinct) 3968 3969 3970def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select: 3971 """ 3972 Initializes a syntax tree from one or multiple SELECT expressions. 3973 3974 Example: 3975 >>> select("col1", "col2").from_("tbl").sql() 3976 'SELECT col1, col2 FROM tbl' 3977 3978 Args: 3979 *expressions: the SQL code string to parse as the expressions of a 3980 SELECT statement. If an Expression instance is passed, this is used as-is. 3981 dialect: the dialect used to parse the input expressions (in the case that an 3982 input expression is a SQL string). 3983 **opts: other options to use to parse the input expressions (again, in the case 3984 that an input expression is a SQL string). 3985 3986 Returns: 3987 Select: the syntax tree for the SELECT statement. 3988 """ 3989 return Select().select(*expressions, dialect=dialect, **opts) 3990 3991 3992def from_(*expressions, dialect=None, **opts) -> Select: 3993 """ 3994 Initializes a syntax tree from a FROM expression. 3995 3996 Example: 3997 >>> from_("tbl").select("col1", "col2").sql() 3998 'SELECT col1, col2 FROM tbl' 3999 4000 Args: 4001 *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a 4002 SELECT statement. If an Expression instance is passed, this is used as-is. 4003 dialect (str): the dialect used to parse the input expression (in the case that the 4004 input expression is a SQL string). 4005 **opts: other options to use to parse the input expressions (again, in the case 4006 that the input expression is a SQL string). 4007 4008 Returns: 4009 Select: the syntax tree for the SELECT statement. 4010 """ 4011 return Select().from_(*expressions, dialect=dialect, **opts) 4012 4013 4014def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update: 4015 """ 4016 Creates an update statement. 4017 4018 Example: 4019 >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() 4020 "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1" 4021 4022 Args: 4023 *properties (Dict[str, Any]): dictionary of properties to set which are 4024 auto converted to sql objects eg None -> NULL 4025 where (str): sql conditional parsed into a WHERE statement 4026 from_ (str): sql statement parsed into a FROM statement 4027 dialect (str): the dialect used to parse the input expressions. 4028 **opts: other options to use to parse the input expressions. 4029 4030 Returns: 4031 Update: the syntax tree for the UPDATE statement. 4032 """ 4033 update = Update(this=maybe_parse(table, into=Table, dialect=dialect)) 4034 update.set( 4035 "expressions", 4036 [ 4037 EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v)) 4038 for k, v in properties.items() 4039 ], 4040 ) 4041 if from_: 4042 update.set( 4043 "from", 4044 maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts), 4045 ) 4046 if isinstance(where, Condition): 4047 where = Where(this=where) 4048 if where: 4049 update.set( 4050 "where", 4051 maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4052 ) 4053 return update 4054 4055 4056def delete(table, where=None, dialect=None, **opts) -> Delete: 4057 """ 4058 Builds a delete statement. 4059 4060 Example: 4061 >>> delete("my_table", where="id > 1").sql() 4062 'DELETE FROM my_table WHERE id > 1' 4063 4064 Args: 4065 where (str|Condition): sql conditional parsed into a WHERE statement 4066 dialect (str): the dialect used to parse the input expressions. 4067 **opts: other options to use to parse the input expressions. 4068 4069 Returns: 4070 Delete: the syntax tree for the DELETE statement. 4071 """ 4072 return Delete( 4073 this=maybe_parse(table, into=Table, dialect=dialect, **opts), 4074 where=Where(this=where) 4075 if isinstance(where, Condition) 4076 else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4077 ) 4078 4079 4080def condition(expression, dialect=None, **opts) -> Condition: 4081 """ 4082 Initialize a logical condition expression. 4083 4084 Example: 4085 >>> condition("x=1").sql() 4086 'x = 1' 4087 4088 This is helpful for composing larger logical syntax trees: 4089 >>> where = condition("x=1") 4090 >>> where = where.and_("y=1") 4091 >>> Select().from_("tbl").select("*").where(where).sql() 4092 'SELECT * FROM tbl WHERE x = 1 AND y = 1' 4093 4094 Args: 4095 *expression (str | Expression): the SQL code string to parse. 4096 If an Expression instance is passed, this is used as-is. 4097 dialect (str): the dialect used to parse the input expression (in the case that the 4098 input expression is a SQL string). 4099 **opts: other options to use to parse the input expressions (again, in the case 4100 that the input expression is a SQL string). 4101 4102 Returns: 4103 Condition: the expression 4104 """ 4105 return maybe_parse( # type: ignore 4106 expression, 4107 into=Condition, 4108 dialect=dialect, 4109 **opts, 4110 ) 4111 4112 4113def and_(*expressions, dialect=None, **opts) -> And: 4114 """ 4115 Combine multiple conditions with an AND logical operator. 4116 4117 Example: 4118 >>> and_("x=1", and_("y=1", "z=1")).sql() 4119 'x = 1 AND (y = 1 AND z = 1)' 4120 4121 Args: 4122 *expressions (str | Expression): the SQL code strings to parse. 4123 If an Expression instance is passed, this is used as-is. 4124 dialect (str): the dialect used to parse the input expression. 4125 **opts: other options to use to parse the input expressions. 4126 4127 Returns: 4128 And: the new condition 4129 """ 4130 return _combine(expressions, And, dialect, **opts) 4131 4132 4133def or_(*expressions, dialect=None, **opts) -> Or: 4134 """ 4135 Combine multiple conditions with an OR logical operator. 4136 4137 Example: 4138 >>> or_("x=1", or_("y=1", "z=1")).sql() 4139 'x = 1 OR (y = 1 OR z = 1)' 4140 4141 Args: 4142 *expressions (str | Expression): the SQL code strings to parse. 4143 If an Expression instance is passed, this is used as-is. 4144 dialect (str): the dialect used to parse the input expression. 4145 **opts: other options to use to parse the input expressions. 4146 4147 Returns: 4148 Or: the new condition 4149 """ 4150 return _combine(expressions, Or, dialect, **opts) 4151 4152 4153def not_(expression, dialect=None, **opts) -> Not: 4154 """ 4155 Wrap a condition with a NOT operator. 4156 4157 Example: 4158 >>> not_("this_suit='black'").sql() 4159 "NOT this_suit = 'black'" 4160 4161 Args: 4162 expression (str | Expression): the SQL code strings to parse. 4163 If an Expression instance is passed, this is used as-is. 4164 dialect (str): the dialect used to parse the input expression. 4165 **opts: other options to use to parse the input expressions. 4166 4167 Returns: 4168 Not: the new condition 4169 """ 4170 this = condition( 4171 expression, 4172 dialect=dialect, 4173 **opts, 4174 ) 4175 return Not(this=_wrap_operator(this)) 4176 4177 4178def paren(expression) -> Paren: 4179 return Paren(this=expression) 4180 4181 4182SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$") 4183 4184 4185@t.overload 4186def to_identifier(name: None, quoted: t.Optional[bool] = None) -> None: 4187 ... 4188 4189 4190@t.overload 4191def to_identifier(name: str | Identifier, quoted: t.Optional[bool] = None) -> Identifier: 4192 ... 4193 4194 4195def to_identifier(name, quoted=None): 4196 """Builds an identifier. 4197 4198 Args: 4199 name: The name to turn into an identifier. 4200 quoted: Whether or not force quote the identifier. 4201 4202 Returns: 4203 The identifier ast node. 4204 """ 4205 4206 if name is None: 4207 return None 4208 4209 if isinstance(name, Identifier): 4210 identifier = name 4211 elif isinstance(name, str): 4212 identifier = Identifier( 4213 this=name, 4214 quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted, 4215 ) 4216 else: 4217 raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}") 4218 return identifier 4219 4220 4221INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*") 4222 4223 4224def to_interval(interval: str | Literal) -> Interval: 4225 """Builds an interval expression from a string like '1 day' or '5 months'.""" 4226 if isinstance(interval, Literal): 4227 if not interval.is_string: 4228 raise ValueError("Invalid interval string.") 4229 4230 interval = interval.this 4231 4232 interval_parts = INTERVAL_STRING_RE.match(interval) # type: ignore 4233 4234 if not interval_parts: 4235 raise ValueError("Invalid interval string.") 4236 4237 return Interval( 4238 this=Literal.string(interval_parts.group(1)), 4239 unit=Var(this=interval_parts.group(2)), 4240 ) 4241 4242 4243@t.overload 4244def to_table(sql_path: str | Table, **kwargs) -> Table: 4245 ... 4246 4247 4248@t.overload 4249def to_table(sql_path: None, **kwargs) -> None: 4250 ... 4251 4252 4253def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]: 4254 """ 4255 Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional. 4256 If a table is passed in then that table is returned. 4257 4258 Args: 4259 sql_path: a `[catalog].[schema].[table]` string. 4260 4261 Returns: 4262 A table expression. 4263 """ 4264 if sql_path is None or isinstance(sql_path, Table): 4265 return sql_path 4266 if not isinstance(sql_path, str): 4267 raise ValueError(f"Invalid type provided for a table: {type(sql_path)}") 4268 4269 catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3)) 4270 return Table(this=table_name, db=db, catalog=catalog, **kwargs) 4271 4272 4273def to_column(sql_path: str | Column, **kwargs) -> Column: 4274 """ 4275 Create a column from a `[table].[column]` sql path. Schema is optional. 4276 4277 If a column is passed in then that column is returned. 4278 4279 Args: 4280 sql_path: `[table].[column]` string 4281 Returns: 4282 Table: A column expression 4283 """ 4284 if sql_path is None or isinstance(sql_path, Column): 4285 return sql_path 4286 if not isinstance(sql_path, str): 4287 raise ValueError(f"Invalid type provided for column: {type(sql_path)}") 4288 table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2)) 4289 return Column(this=column_name, table=table_name, **kwargs) 4290 4291 4292def alias_( 4293 expression: str | Expression, 4294 alias: str | Identifier, 4295 table: bool | t.Sequence[str | Identifier] = False, 4296 quoted: t.Optional[bool] = None, 4297 dialect: DialectType = None, 4298 **opts, 4299): 4300 """Create an Alias expression. 4301 4302 Example: 4303 >>> alias_('foo', 'bar').sql() 4304 'foo AS bar' 4305 4306 >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() 4307 '(SELECT 1, 2) AS bar(a, b)' 4308 4309 Args: 4310 expression: the SQL code strings to parse. 4311 If an Expression instance is passed, this is used as-is. 4312 alias: the alias name to use. If the name has 4313 special characters it is quoted. 4314 table: Whether or not to create a table alias, can also be a list of columns. 4315 quoted: whether or not to quote the alias 4316 dialect: the dialect used to parse the input expression. 4317 **opts: other options to use to parse the input expressions. 4318 4319 Returns: 4320 Alias: the aliased expression 4321 """ 4322 exp = maybe_parse(expression, dialect=dialect, **opts) 4323 alias = to_identifier(alias, quoted=quoted) 4324 4325 if table: 4326 table_alias = TableAlias(this=alias) 4327 exp.set("alias", table_alias) 4328 4329 if not isinstance(table, bool): 4330 for column in table: 4331 table_alias.append("columns", to_identifier(column, quoted=quoted)) 4332 4333 return exp 4334 4335 # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in 4336 # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node 4337 # for the complete Window expression. 4338 # 4339 # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls 4340 4341 if "alias" in exp.arg_types and not isinstance(exp, Window): 4342 exp = exp.copy() 4343 exp.set("alias", alias) 4344 return exp 4345 return Alias(this=exp, alias=alias) 4346 4347 4348def subquery(expression, alias=None, dialect=None, **opts): 4349 """ 4350 Build a subquery expression. 4351 4352 Example: 4353 >>> subquery('select x from tbl', 'bar').select('x').sql() 4354 'SELECT x FROM (SELECT x FROM tbl) AS bar' 4355 4356 Args: 4357 expression (str | Expression): the SQL code strings to parse. 4358 If an Expression instance is passed, this is used as-is. 4359 alias (str | Expression): the alias name to use. 4360 dialect (str): the dialect used to parse the input expression. 4361 **opts: other options to use to parse the input expressions. 4362 4363 Returns: 4364 Select: a new select with the subquery expression included 4365 """ 4366 4367 expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias) 4368 return Select().from_(expression, dialect=dialect, **opts) 4369 4370 4371def column( 4372 col: str | Identifier, 4373 table: t.Optional[str | Identifier] = None, 4374 schema: t.Optional[str | Identifier] = None, 4375 quoted: t.Optional[bool] = None, 4376) -> Column: 4377 """ 4378 Build a Column. 4379 4380 Args: 4381 col: column name 4382 table: table name 4383 schema: schema name 4384 quoted: whether or not to force quote each part 4385 Returns: 4386 Column: column instance 4387 """ 4388 return Column( 4389 this=to_identifier(col, quoted=quoted), 4390 table=to_identifier(table, quoted=quoted), 4391 schema=to_identifier(schema, quoted=quoted), 4392 ) 4393 4394 4395def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast: 4396 """Cast an expression to a data type. 4397 4398 Example: 4399 >>> cast('x + 1', 'int').sql() 4400 'CAST(x + 1 AS INT)' 4401 4402 Args: 4403 expression: The expression to cast. 4404 to: The datatype to cast to. 4405 4406 Returns: 4407 A cast node. 4408 """ 4409 expression = maybe_parse(expression, **opts) 4410 return Cast(this=expression, to=DataType.build(to, **opts)) 4411 4412 4413def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table: 4414 """Build a Table. 4415 4416 Args: 4417 table (str | Expression): column name 4418 db (str | Expression): db name 4419 catalog (str | Expression): catalog name 4420 4421 Returns: 4422 Table: table instance 4423 """ 4424 return Table( 4425 this=to_identifier(table, quoted=quoted), 4426 db=to_identifier(db, quoted=quoted), 4427 catalog=to_identifier(catalog, quoted=quoted), 4428 alias=TableAlias(this=to_identifier(alias)) if alias else None, 4429 ) 4430 4431 4432def values( 4433 values: t.Iterable[t.Tuple[t.Any, ...]], 4434 alias: t.Optional[str] = None, 4435 columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None, 4436) -> Values: 4437 """Build VALUES statement. 4438 4439 Example: 4440 >>> values([(1, '2')]).sql() 4441 "VALUES (1, '2')" 4442 4443 Args: 4444 values: values statements that will be converted to SQL 4445 alias: optional alias 4446 columns: Optional list of ordered column names or ordered dictionary of column names to types. 4447 If either are provided then an alias is also required. 4448 If a dictionary is provided then the first column of the values will be casted to the expected type 4449 in order to help with type inference. 4450 4451 Returns: 4452 Values: the Values expression object 4453 """ 4454 if columns and not alias: 4455 raise ValueError("Alias is required when providing columns") 4456 table_alias = ( 4457 TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns]) 4458 if columns 4459 else TableAlias(this=to_identifier(alias) if alias else None) 4460 ) 4461 expressions = [convert(tup) for tup in values] 4462 if columns and isinstance(columns, dict): 4463 types = list(columns.values()) 4464 expressions[0].set( 4465 "expressions", 4466 [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)], 4467 ) 4468 return Values( 4469 expressions=expressions, 4470 alias=table_alias, 4471 ) 4472 4473 4474def var(name: t.Optional[str | Expression]) -> Var: 4475 """Build a SQL variable. 4476 4477 Example: 4478 >>> repr(var('x')) 4479 '(VAR this: x)' 4480 4481 >>> repr(var(column('x', table='y'))) 4482 '(VAR this: x)' 4483 4484 Args: 4485 name: The name of the var or an expression who's name will become the var. 4486 4487 Returns: 4488 The new variable node. 4489 """ 4490 if not name: 4491 raise ValueError(f"Cannot convert empty name into var.") 4492 4493 if isinstance(name, Expression): 4494 name = name.name 4495 return Var(this=name) 4496 4497 4498def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable: 4499 """Build ALTER TABLE... RENAME... expression 4500 4501 Args: 4502 old_name: The old name of the table 4503 new_name: The new name of the table 4504 4505 Returns: 4506 Alter table expression 4507 """ 4508 old_table = to_table(old_name) 4509 new_table = to_table(new_name) 4510 return AlterTable( 4511 this=old_table, 4512 actions=[ 4513 RenameTable(this=new_table), 4514 ], 4515 ) 4516 4517 4518def convert(value) -> Expression: 4519 """Convert a python value into an expression object. 4520 4521 Raises an error if a conversion is not possible. 4522 4523 Args: 4524 value (Any): a python object 4525 4526 Returns: 4527 Expression: the equivalent expression object 4528 """ 4529 if isinstance(value, Expression): 4530 return value 4531 if value is None: 4532 return NULL 4533 if isinstance(value, bool): 4534 return Boolean(this=value) 4535 if isinstance(value, str): 4536 return Literal.string(value) 4537 if isinstance(value, float) and math.isnan(value): 4538 return NULL 4539 if isinstance(value, numbers.Number): 4540 return Literal.number(value) 4541 if isinstance(value, tuple): 4542 return Tuple(expressions=[convert(v) for v in value]) 4543 if isinstance(value, list): 4544 return Array(expressions=[convert(v) for v in value]) 4545 if isinstance(value, dict): 4546 return Map( 4547 keys=[convert(k) for k in value], 4548 values=[convert(v) for v in value.values()], 4549 ) 4550 if isinstance(value, datetime.datetime): 4551 datetime_literal = Literal.string( 4552 (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat() 4553 ) 4554 return TimeStrToTime(this=datetime_literal) 4555 if isinstance(value, datetime.date): 4556 date_literal = Literal.string(value.strftime("%Y-%m-%d")) 4557 return DateStrToDate(this=date_literal) 4558 raise ValueError(f"Cannot convert {value}") 4559 4560 4561def replace_children(expression, fun): 4562 """ 4563 Replace children of an expression with the result of a lambda fun(child) -> exp. 4564 """ 4565 for k, v in expression.args.items(): 4566 is_list_arg = isinstance(v, list) 4567 4568 child_nodes = v if is_list_arg else [v] 4569 new_child_nodes = [] 4570 4571 for cn in child_nodes: 4572 if isinstance(cn, Expression): 4573 for child_node in ensure_collection(fun(cn)): 4574 new_child_nodes.append(child_node) 4575 child_node.parent = expression 4576 child_node.arg_key = k 4577 else: 4578 new_child_nodes.append(cn) 4579 4580 expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0) 4581 4582 4583def column_table_names(expression): 4584 """ 4585 Return all table names referenced through columns in an expression. 4586 4587 Example: 4588 >>> import sqlglot 4589 >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) 4590 ['c', 'a'] 4591 4592 Args: 4593 expression (sqlglot.Expression): expression to find table names 4594 4595 Returns: 4596 list: A list of unique names 4597 """ 4598 return list(dict.fromkeys(column.table for column in expression.find_all(Column))) 4599 4600 4601def table_name(table) -> str: 4602 """Get the full name of a table as a string. 4603 4604 Args: 4605 table (exp.Table | str): table expression node or string. 4606 4607 Examples: 4608 >>> from sqlglot import exp, parse_one 4609 >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 4610 'a.b.c' 4611 4612 Returns: 4613 The table name. 4614 """ 4615 4616 table = maybe_parse(table, into=Table) 4617 4618 if not table: 4619 raise ValueError(f"Cannot parse {table}") 4620 4621 return ".".join( 4622 part 4623 for part in ( 4624 table.text("catalog"), 4625 table.text("db"), 4626 table.name, 4627 ) 4628 if part 4629 ) 4630 4631 4632def replace_tables(expression, mapping): 4633 """Replace all tables in expression according to the mapping. 4634 4635 Args: 4636 expression (sqlglot.Expression): expression node to be transformed and replaced. 4637 mapping (Dict[str, str]): mapping of table names. 4638 4639 Examples: 4640 >>> from sqlglot import exp, parse_one 4641 >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 4642 'SELECT * FROM c' 4643 4644 Returns: 4645 The mapped expression. 4646 """ 4647 4648 def _replace_tables(node): 4649 if isinstance(node, Table): 4650 new_name = mapping.get(table_name(node)) 4651 if new_name: 4652 return to_table( 4653 new_name, 4654 **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")}, 4655 ) 4656 return node 4657 4658 return expression.transform(_replace_tables) 4659 4660 4661def replace_placeholders(expression, *args, **kwargs): 4662 """Replace placeholders in an expression. 4663 4664 Args: 4665 expression (sqlglot.Expression): expression node to be transformed and replaced. 4666 args: positional names that will substitute unnamed placeholders in the given order. 4667 kwargs: keyword arguments that will substitute named placeholders. 4668 4669 Examples: 4670 >>> from sqlglot import exp, parse_one 4671 >>> replace_placeholders( 4672 ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" 4673 ... ).sql() 4674 'SELECT * FROM foo WHERE a = b' 4675 4676 Returns: 4677 The mapped expression. 4678 """ 4679 4680 def _replace_placeholders(node, args, **kwargs): 4681 if isinstance(node, Placeholder): 4682 if node.name: 4683 new_name = kwargs.get(node.name) 4684 if new_name: 4685 return to_identifier(new_name) 4686 else: 4687 try: 4688 return to_identifier(next(args)) 4689 except StopIteration: 4690 pass 4691 return node 4692 4693 return expression.transform(_replace_placeholders, iter(args), **kwargs) 4694 4695 4696def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression: 4697 """Transforms an expression by expanding all referenced sources into subqueries. 4698 4699 Examples: 4700 >>> from sqlglot import parse_one 4701 >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 4702 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */' 4703 4704 Args: 4705 expression: The expression to expand. 4706 sources: A dictionary of name to Subqueryables. 4707 copy: Whether or not to copy the expression during transformation. Defaults to True. 4708 4709 Returns: 4710 The transformed expression. 4711 """ 4712 4713 def _expand(node: Expression): 4714 if isinstance(node, Table): 4715 name = table_name(node) 4716 source = sources.get(name) 4717 if source: 4718 subquery = source.subquery(node.alias or name) 4719 subquery.comments = [f"source: {name}"] 4720 return subquery 4721 return node 4722 4723 return expression.transform(_expand, copy=copy) 4724 4725 4726def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func: 4727 """ 4728 Returns a Func expression. 4729 4730 Examples: 4731 >>> func("abs", 5).sql() 4732 'ABS(5)' 4733 4734 >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 4735 'CAST(5 AS DOUBLE)' 4736 4737 Args: 4738 name: the name of the function to build. 4739 args: the args used to instantiate the function of interest. 4740 dialect: the source dialect. 4741 kwargs: the kwargs used to instantiate the function of interest. 4742 4743 Note: 4744 The arguments `args` and `kwargs` are mutually exclusive. 4745 4746 Returns: 4747 An instance of the function of interest, or an anonymous function, if `name` doesn't 4748 correspond to an existing `sqlglot.expressions.Func` class. 4749 """ 4750 if args and kwargs: 4751 raise ValueError("Can't use both args and kwargs to instantiate a function.") 4752 4753 from sqlglot.dialects.dialect import Dialect 4754 4755 args = tuple(convert(arg) for arg in args) 4756 kwargs = {key: convert(value) for key, value in kwargs.items()} 4757 4758 parser = Dialect.get_or_raise(dialect)().parser() 4759 from_args_list = parser.FUNCTIONS.get(name.upper()) 4760 4761 if from_args_list: 4762 function = from_args_list(args) if args else from_args_list.__self__(**kwargs) # type: ignore 4763 else: 4764 kwargs = kwargs or {"expressions": args} 4765 function = Anonymous(this=name, **kwargs) 4766 4767 for error_message in function.error_messages(args): 4768 raise ValueError(error_message) 4769 4770 return function 4771 4772 4773def true(): 4774 """ 4775 Returns a true Boolean expression. 4776 """ 4777 return Boolean(this=True) 4778 4779 4780def false(): 4781 """ 4782 Returns a false Boolean expression. 4783 """ 4784 return Boolean(this=False) 4785 4786 4787def null(): 4788 """ 4789 Returns a Null expression. 4790 """ 4791 return Null() 4792 4793 4794# TODO: deprecate this 4795TRUE = Boolean(this=True) 4796FALSE = Boolean(this=False) 4797NULL = Null()
54class Expression(metaclass=_Expression): 55 """ 56 The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary 57 context, such as its child expressions, their names (arg keys), and whether a given child expression 58 is optional or not. 59 60 Attributes: 61 key: a unique key for each class in the Expression hierarchy. This is useful for hashing 62 and representing expressions as strings. 63 arg_types: determines what arguments (child nodes) are supported by an expression. It 64 maps arg keys to booleans that indicate whether the corresponding args are optional. 65 66 Example: 67 >>> class Foo(Expression): 68 ... arg_types = {"this": True, "expression": False} 69 70 The above definition informs us that Foo is an Expression that requires an argument called 71 "this" and may also optionally receive an argument called "expression". 72 73 Args: 74 args: a mapping used for retrieving the arguments of an expression, given their arg keys. 75 parent: a reference to the parent expression (or None, in case of root expressions). 76 arg_key: the arg key an expression is associated with, i.e. the name its parent expression 77 uses to refer to it. 78 comments: a list of comments that are associated with a given expression. This is used in 79 order to preserve comments when transpiling SQL code. 80 _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the 81 optimizer, in order to enable some transformations that require type information. 82 """ 83 84 key = "expression" 85 arg_types = {"this": True} 86 __slots__ = ("args", "parent", "arg_key", "comments", "_type") 87 88 def __init__(self, **args: t.Any): 89 self.args: t.Dict[str, t.Any] = args 90 self.parent: t.Optional[Expression] = None 91 self.arg_key: t.Optional[str] = None 92 self.comments: t.Optional[t.List[str]] = None 93 self._type: t.Optional[DataType] = None 94 95 for arg_key, value in self.args.items(): 96 self._set_parent(arg_key, value) 97 98 def __eq__(self, other) -> bool: 99 return type(self) is type(other) and _norm_args(self) == _norm_args(other) 100 101 def __hash__(self) -> int: 102 return hash( 103 ( 104 self.key, 105 tuple( 106 (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items() 107 ), 108 ) 109 ) 110 111 @property 112 def this(self): 113 """ 114 Retrieves the argument with key "this". 115 """ 116 return self.args.get("this") 117 118 @property 119 def expression(self): 120 """ 121 Retrieves the argument with key "expression". 122 """ 123 return self.args.get("expression") 124 125 @property 126 def expressions(self): 127 """ 128 Retrieves the argument with key "expressions". 129 """ 130 return self.args.get("expressions") or [] 131 132 def text(self, key) -> str: 133 """ 134 Returns a textual representation of the argument corresponding to "key". This can only be used 135 for args that are strings or leaf Expression instances, such as identifiers and literals. 136 """ 137 field = self.args.get(key) 138 if isinstance(field, str): 139 return field 140 if isinstance(field, (Identifier, Literal, Var)): 141 return field.this 142 if isinstance(field, (Star, Null)): 143 return field.name 144 return "" 145 146 @property 147 def is_string(self) -> bool: 148 """ 149 Checks whether a Literal expression is a string. 150 """ 151 return isinstance(self, Literal) and self.args["is_string"] 152 153 @property 154 def is_number(self) -> bool: 155 """ 156 Checks whether a Literal expression is a number. 157 """ 158 return isinstance(self, Literal) and not self.args["is_string"] 159 160 @property 161 def is_int(self) -> bool: 162 """ 163 Checks whether a Literal expression is an integer. 164 """ 165 if self.is_number: 166 try: 167 int(self.name) 168 return True 169 except ValueError: 170 pass 171 return False 172 173 @property 174 def is_star(self) -> bool: 175 """Checks whether an expression is a star.""" 176 return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star)) 177 178 @property 179 def alias(self) -> str: 180 """ 181 Returns the alias of the expression, or an empty string if it's not aliased. 182 """ 183 if isinstance(self.args.get("alias"), TableAlias): 184 return self.args["alias"].name 185 return self.text("alias") 186 187 @property 188 def name(self) -> str: 189 return self.text("this") 190 191 @property 192 def alias_or_name(self): 193 return self.alias or self.name 194 195 @property 196 def output_name(self): 197 """ 198 Name of the output column if this expression is a selection. 199 200 If the Expression has no output name, an empty string is returned. 201 202 Example: 203 >>> from sqlglot import parse_one 204 >>> parse_one("SELECT a").expressions[0].output_name 205 'a' 206 >>> parse_one("SELECT b AS c").expressions[0].output_name 207 'c' 208 >>> parse_one("SELECT 1 + 2").expressions[0].output_name 209 '' 210 """ 211 return "" 212 213 @property 214 def type(self) -> t.Optional[DataType]: 215 return self._type 216 217 @type.setter 218 def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None: 219 if dtype and not isinstance(dtype, DataType): 220 dtype = DataType.build(dtype) 221 self._type = dtype # type: ignore 222 223 def __deepcopy__(self, memo): 224 copy = self.__class__(**deepcopy(self.args)) 225 copy.comments = self.comments 226 copy.type = self.type 227 return copy 228 229 def copy(self): 230 """ 231 Returns a deep copy of the expression. 232 """ 233 new = deepcopy(self) 234 new.parent = self.parent 235 for item, parent, _ in new.bfs(): 236 if isinstance(item, Expression) and parent: 237 item.parent = parent 238 return new 239 240 def append(self, arg_key, value): 241 """ 242 Appends value to arg_key if it's a list or sets it as a new list. 243 244 Args: 245 arg_key (str): name of the list expression arg 246 value (Any): value to append to the list 247 """ 248 if not isinstance(self.args.get(arg_key), list): 249 self.args[arg_key] = [] 250 self.args[arg_key].append(value) 251 self._set_parent(arg_key, value) 252 253 def set(self, arg_key, value): 254 """ 255 Sets `arg_key` to `value`. 256 257 Args: 258 arg_key (str): name of the expression arg. 259 value: value to set the arg to. 260 """ 261 self.args[arg_key] = value 262 self._set_parent(arg_key, value) 263 264 def _set_parent(self, arg_key, value): 265 if isinstance(value, Expression): 266 value.parent = self 267 value.arg_key = arg_key 268 elif isinstance(value, list): 269 for v in value: 270 if isinstance(v, Expression): 271 v.parent = self 272 v.arg_key = arg_key 273 274 @property 275 def depth(self): 276 """ 277 Returns the depth of this tree. 278 """ 279 if self.parent: 280 return self.parent.depth + 1 281 return 0 282 283 def find(self, *expression_types, bfs=True): 284 """ 285 Returns the first node in this tree which matches at least one of 286 the specified types. 287 288 Args: 289 expression_types (type): the expression type(s) to match. 290 291 Returns: 292 The node which matches the criteria or None if no such node was found. 293 """ 294 return next(self.find_all(*expression_types, bfs=bfs), None) 295 296 def find_all(self, *expression_types, bfs=True): 297 """ 298 Returns a generator object which visits all nodes in this tree and only 299 yields those that match at least one of the specified expression types. 300 301 Args: 302 expression_types (type): the expression type(s) to match. 303 304 Returns: 305 The generator object. 306 """ 307 for expression, _, _ in self.walk(bfs=bfs): 308 if isinstance(expression, expression_types): 309 yield expression 310 311 def find_ancestor(self, *expression_types): 312 """ 313 Returns a nearest parent matching expression_types. 314 315 Args: 316 expression_types (type): the expression type(s) to match. 317 318 Returns: 319 The parent node. 320 """ 321 ancestor = self.parent 322 while ancestor and not isinstance(ancestor, expression_types): 323 ancestor = ancestor.parent 324 return ancestor 325 326 @property 327 def parent_select(self): 328 """ 329 Returns the parent select statement. 330 """ 331 return self.find_ancestor(Select) 332 333 def walk(self, bfs=True, prune=None): 334 """ 335 Returns a generator object which visits all nodes in this tree. 336 337 Args: 338 bfs (bool): if set to True the BFS traversal order will be applied, 339 otherwise the DFS traversal will be used instead. 340 prune ((node, parent, arg_key) -> bool): callable that returns True if 341 the generator should stop traversing this branch of the tree. 342 343 Returns: 344 the generator object. 345 """ 346 if bfs: 347 yield from self.bfs(prune=prune) 348 else: 349 yield from self.dfs(prune=prune) 350 351 def dfs(self, parent=None, key=None, prune=None): 352 """ 353 Returns a generator object which visits all nodes in this tree in 354 the DFS (Depth-first) order. 355 356 Returns: 357 The generator object. 358 """ 359 parent = parent or self.parent 360 yield self, parent, key 361 if prune and prune(self, parent, key): 362 return 363 364 for k, v in self.args.items(): 365 for node in ensure_collection(v): 366 if isinstance(node, Expression): 367 yield from node.dfs(self, k, prune) 368 369 def bfs(self, prune=None): 370 """ 371 Returns a generator object which visits all nodes in this tree in 372 the BFS (Breadth-first) order. 373 374 Returns: 375 The generator object. 376 """ 377 queue = deque([(self, self.parent, None)]) 378 379 while queue: 380 item, parent, key = queue.popleft() 381 382 yield item, parent, key 383 if prune and prune(item, parent, key): 384 continue 385 386 if isinstance(item, Expression): 387 for k, v in item.args.items(): 388 for node in ensure_collection(v): 389 if isinstance(node, Expression): 390 queue.append((node, item, k)) 391 392 def unnest(self): 393 """ 394 Returns the first non parenthesis child or self. 395 """ 396 expression = self 397 while isinstance(expression, Paren): 398 expression = expression.this 399 return expression 400 401 def unalias(self): 402 """ 403 Returns the inner expression if this is an Alias. 404 """ 405 if isinstance(self, Alias): 406 return self.this 407 return self 408 409 def unnest_operands(self): 410 """ 411 Returns unnested operands as a tuple. 412 """ 413 return tuple(arg.unnest() for arg in self.args.values() if arg) 414 415 def flatten(self, unnest=True): 416 """ 417 Returns a generator which yields child nodes who's parents are the same class. 418 419 A AND B AND C -> [A, B, C] 420 """ 421 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 422 if not isinstance(node, self.__class__): 423 yield node.unnest() if unnest else node 424 425 def __str__(self): 426 return self.sql() 427 428 def __repr__(self): 429 return self._to_s() 430 431 def sql(self, dialect: DialectType = None, **opts) -> str: 432 """ 433 Returns SQL string representation of this tree. 434 435 Args: 436 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 437 opts: other `sqlglot.generator.Generator` options. 438 439 Returns: 440 The SQL string. 441 """ 442 from sqlglot.dialects import Dialect 443 444 return Dialect.get_or_raise(dialect)().generate(self, **opts) 445 446 def _to_s(self, hide_missing: bool = True, level: int = 0) -> str: 447 indent = "" if not level else "\n" 448 indent += "".join([" "] * level) 449 left = f"({self.key.upper()} " 450 451 args: t.Dict[str, t.Any] = { 452 k: ", ".join( 453 v._to_s(hide_missing=hide_missing, level=level + 1) 454 if hasattr(v, "_to_s") 455 else str(v) 456 for v in ensure_collection(vs) 457 if v is not None 458 ) 459 for k, vs in self.args.items() 460 } 461 args["comments"] = self.comments 462 args["type"] = self.type 463 args = {k: v for k, v in args.items() if v or not hide_missing} 464 465 right = ", ".join(f"{k}: {v}" for k, v in args.items()) 466 right += ")" 467 468 return indent + left + right 469 470 def transform(self, fun, *args, copy=True, **kwargs): 471 """ 472 Recursively visits all tree nodes (excluding already transformed ones) 473 and applies the given transformation function to each node. 474 475 Args: 476 fun (function): a function which takes a node as an argument and returns a 477 new transformed node or the same node without modifications. If the function 478 returns None, then the corresponding node will be removed from the syntax tree. 479 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 480 modified in place. 481 482 Returns: 483 The transformed tree. 484 """ 485 node = self.copy() if copy else self 486 new_node = fun(node, *args, **kwargs) 487 488 if new_node is None or not isinstance(new_node, Expression): 489 return new_node 490 if new_node is not node: 491 new_node.parent = node.parent 492 return new_node 493 494 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 495 return new_node 496 497 def replace(self, expression): 498 """ 499 Swap out this expression with a new expression. 500 501 For example:: 502 503 >>> tree = Select().select("x").from_("tbl") 504 >>> tree.find(Column).replace(Column(this="y")) 505 (COLUMN this: y) 506 >>> tree.sql() 507 'SELECT y FROM tbl' 508 509 Args: 510 expression (Expression|None): new node 511 512 Returns: 513 The new expression or expressions. 514 """ 515 if not self.parent: 516 return expression 517 518 parent = self.parent 519 self.parent = None 520 521 replace_children(parent, lambda child: expression if child is self else child) 522 return expression 523 524 def pop(self): 525 """ 526 Remove this expression from its AST. 527 """ 528 self.replace(None) 529 530 def assert_is(self, type_): 531 """ 532 Assert that this `Expression` is an instance of `type_`. 533 534 If it is NOT an instance of `type_`, this raises an assertion error. 535 Otherwise, this returns this expression. 536 537 Examples: 538 This is useful for type security in chained expressions: 539 540 >>> import sqlglot 541 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 542 'SELECT x, z FROM y' 543 """ 544 assert isinstance(self, type_) 545 return self 546 547 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 548 """ 549 Checks if this expression is valid (e.g. all mandatory args are set). 550 551 Args: 552 args: a sequence of values that were used to instantiate a Func expression. This is used 553 to check that the provided arguments don't exceed the function argument limit. 554 555 Returns: 556 A list of error messages for all possible errors that were found. 557 """ 558 errors: t.List[str] = [] 559 560 for k in self.args: 561 if k not in self.arg_types: 562 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 563 for k, mandatory in self.arg_types.items(): 564 v = self.args.get(k) 565 if mandatory and (v is None or (isinstance(v, list) and not v)): 566 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 567 568 if ( 569 args 570 and isinstance(self, Func) 571 and len(args) > len(self.arg_types) 572 and not self.is_var_len_args 573 ): 574 errors.append( 575 f"The number of provided arguments ({len(args)}) is greater than " 576 f"the maximum number of supported arguments ({len(self.arg_types)})" 577 ) 578 579 return errors 580 581 def dump(self): 582 """ 583 Dump this Expression to a JSON-serializable dict. 584 """ 585 from sqlglot.serde import dump 586 587 return dump(self) 588 589 @classmethod 590 def load(cls, obj): 591 """ 592 Load a dict (as returned by `Expression.dump`) into an Expression instance. 593 """ 594 from sqlglot.serde import load 595 596 return load(obj)
The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.
Attributes:
- key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
- arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
Example:
>>> class Foo(Expression): ... arg_types = {"this": True, "expression": False}The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".
Arguments:
- args: a mapping used for retrieving the arguments of an expression, given their arg keys.
- parent: a reference to the parent expression (or None, in case of root expressions).
- arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
- comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
- _type: the
sqlglot.expressions.DataTypetype of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
88 def __init__(self, **args: t.Any): 89 self.args: t.Dict[str, t.Any] = args 90 self.parent: t.Optional[Expression] = None 91 self.arg_key: t.Optional[str] = None 92 self.comments: t.Optional[t.List[str]] = None 93 self._type: t.Optional[DataType] = None 94 95 for arg_key, value in self.args.items(): 96 self._set_parent(arg_key, value)
132 def text(self, key) -> str: 133 """ 134 Returns a textual representation of the argument corresponding to "key". This can only be used 135 for args that are strings or leaf Expression instances, such as identifiers and literals. 136 """ 137 field = self.args.get(key) 138 if isinstance(field, str): 139 return field 140 if isinstance(field, (Identifier, Literal, Var)): 141 return field.this 142 if isinstance(field, (Star, Null)): 143 return field.name 144 return ""
Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
229 def copy(self): 230 """ 231 Returns a deep copy of the expression. 232 """ 233 new = deepcopy(self) 234 new.parent = self.parent 235 for item, parent, _ in new.bfs(): 236 if isinstance(item, Expression) and parent: 237 item.parent = parent 238 return new
Returns a deep copy of the expression.
240 def append(self, arg_key, value): 241 """ 242 Appends value to arg_key if it's a list or sets it as a new list. 243 244 Args: 245 arg_key (str): name of the list expression arg 246 value (Any): value to append to the list 247 """ 248 if not isinstance(self.args.get(arg_key), list): 249 self.args[arg_key] = [] 250 self.args[arg_key].append(value) 251 self._set_parent(arg_key, value)
Appends value to arg_key if it's a list or sets it as a new list.
Arguments:
- arg_key (str): name of the list expression arg
- value (Any): value to append to the list
253 def set(self, arg_key, value): 254 """ 255 Sets `arg_key` to `value`. 256 257 Args: 258 arg_key (str): name of the expression arg. 259 value: value to set the arg to. 260 """ 261 self.args[arg_key] = value 262 self._set_parent(arg_key, value)
Sets arg_key to value.
Arguments:
- arg_key (str): name of the expression arg.
- value: value to set the arg to.
283 def find(self, *expression_types, bfs=True): 284 """ 285 Returns the first node in this tree which matches at least one of 286 the specified types. 287 288 Args: 289 expression_types (type): the expression type(s) to match. 290 291 Returns: 292 The node which matches the criteria or None if no such node was found. 293 """ 294 return next(self.find_all(*expression_types, bfs=bfs), None)
Returns the first node in this tree which matches at least one of the specified types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The node which matches the criteria or None if no such node was found.
296 def find_all(self, *expression_types, bfs=True): 297 """ 298 Returns a generator object which visits all nodes in this tree and only 299 yields those that match at least one of the specified expression types. 300 301 Args: 302 expression_types (type): the expression type(s) to match. 303 304 Returns: 305 The generator object. 306 """ 307 for expression, _, _ in self.walk(bfs=bfs): 308 if isinstance(expression, expression_types): 309 yield expression
Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The generator object.
311 def find_ancestor(self, *expression_types): 312 """ 313 Returns a nearest parent matching expression_types. 314 315 Args: 316 expression_types (type): the expression type(s) to match. 317 318 Returns: 319 The parent node. 320 """ 321 ancestor = self.parent 322 while ancestor and not isinstance(ancestor, expression_types): 323 ancestor = ancestor.parent 324 return ancestor
Returns a nearest parent matching expression_types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The parent node.
333 def walk(self, bfs=True, prune=None): 334 """ 335 Returns a generator object which visits all nodes in this tree. 336 337 Args: 338 bfs (bool): if set to True the BFS traversal order will be applied, 339 otherwise the DFS traversal will be used instead. 340 prune ((node, parent, arg_key) -> bool): callable that returns True if 341 the generator should stop traversing this branch of the tree. 342 343 Returns: 344 the generator object. 345 """ 346 if bfs: 347 yield from self.bfs(prune=prune) 348 else: 349 yield from self.dfs(prune=prune)
Returns a generator object which visits all nodes in this tree.
Arguments:
- bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
- prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:
the generator object.
351 def dfs(self, parent=None, key=None, prune=None): 352 """ 353 Returns a generator object which visits all nodes in this tree in 354 the DFS (Depth-first) order. 355 356 Returns: 357 The generator object. 358 """ 359 parent = parent or self.parent 360 yield self, parent, key 361 if prune and prune(self, parent, key): 362 return 363 364 for k, v in self.args.items(): 365 for node in ensure_collection(v): 366 if isinstance(node, Expression): 367 yield from node.dfs(self, k, prune)
Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.
Returns:
The generator object.
369 def bfs(self, prune=None): 370 """ 371 Returns a generator object which visits all nodes in this tree in 372 the BFS (Breadth-first) order. 373 374 Returns: 375 The generator object. 376 """ 377 queue = deque([(self, self.parent, None)]) 378 379 while queue: 380 item, parent, key = queue.popleft() 381 382 yield item, parent, key 383 if prune and prune(item, parent, key): 384 continue 385 386 if isinstance(item, Expression): 387 for k, v in item.args.items(): 388 for node in ensure_collection(v): 389 if isinstance(node, Expression): 390 queue.append((node, item, k))
Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.
Returns:
The generator object.
392 def unnest(self): 393 """ 394 Returns the first non parenthesis child or self. 395 """ 396 expression = self 397 while isinstance(expression, Paren): 398 expression = expression.this 399 return expression
Returns the first non parenthesis child or self.
401 def unalias(self): 402 """ 403 Returns the inner expression if this is an Alias. 404 """ 405 if isinstance(self, Alias): 406 return self.this 407 return self
Returns the inner expression if this is an Alias.
409 def unnest_operands(self): 410 """ 411 Returns unnested operands as a tuple. 412 """ 413 return tuple(arg.unnest() for arg in self.args.values() if arg)
Returns unnested operands as a tuple.
415 def flatten(self, unnest=True): 416 """ 417 Returns a generator which yields child nodes who's parents are the same class. 418 419 A AND B AND C -> [A, B, C] 420 """ 421 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 422 if not isinstance(node, self.__class__): 423 yield node.unnest() if unnest else node
Returns a generator which yields child nodes who's parents are the same class.
A AND B AND C -> [A, B, C]
431 def sql(self, dialect: DialectType = None, **opts) -> str: 432 """ 433 Returns SQL string representation of this tree. 434 435 Args: 436 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 437 opts: other `sqlglot.generator.Generator` options. 438 439 Returns: 440 The SQL string. 441 """ 442 from sqlglot.dialects import Dialect 443 444 return Dialect.get_or_raise(dialect)().generate(self, **opts)
Returns SQL string representation of this tree.
Arguments:
- dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
- opts: other
sqlglot.generator.Generatoroptions.
Returns:
The SQL string.
470 def transform(self, fun, *args, copy=True, **kwargs): 471 """ 472 Recursively visits all tree nodes (excluding already transformed ones) 473 and applies the given transformation function to each node. 474 475 Args: 476 fun (function): a function which takes a node as an argument and returns a 477 new transformed node or the same node without modifications. If the function 478 returns None, then the corresponding node will be removed from the syntax tree. 479 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 480 modified in place. 481 482 Returns: 483 The transformed tree. 484 """ 485 node = self.copy() if copy else self 486 new_node = fun(node, *args, **kwargs) 487 488 if new_node is None or not isinstance(new_node, Expression): 489 return new_node 490 if new_node is not node: 491 new_node.parent = node.parent 492 return new_node 493 494 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 495 return new_node
Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.
Arguments:
- fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
- copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:
The transformed tree.
497 def replace(self, expression): 498 """ 499 Swap out this expression with a new expression. 500 501 For example:: 502 503 >>> tree = Select().select("x").from_("tbl") 504 >>> tree.find(Column).replace(Column(this="y")) 505 (COLUMN this: y) 506 >>> tree.sql() 507 'SELECT y FROM tbl' 508 509 Args: 510 expression (Expression|None): new node 511 512 Returns: 513 The new expression or expressions. 514 """ 515 if not self.parent: 516 return expression 517 518 parent = self.parent 519 self.parent = None 520 521 replace_children(parent, lambda child: expression if child is self else child) 522 return expression
Swap out this expression with a new expression.
For example::
>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
- expression (Expression|None): new node
Returns:
The new expression or expressions.
530 def assert_is(self, type_): 531 """ 532 Assert that this `Expression` is an instance of `type_`. 533 534 If it is NOT an instance of `type_`, this raises an assertion error. 535 Otherwise, this returns this expression. 536 537 Examples: 538 This is useful for type security in chained expressions: 539 540 >>> import sqlglot 541 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 542 'SELECT x, z FROM y' 543 """ 544 assert isinstance(self, type_) 545 return self
Assert that this Expression is an instance of type_.
If it is NOT an instance of type_, this raises an assertion error.
Otherwise, this returns this expression.
Examples:
This is useful for type security in chained expressions:
>>> import sqlglot >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 'SELECT x, z FROM y'
547 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 548 """ 549 Checks if this expression is valid (e.g. all mandatory args are set). 550 551 Args: 552 args: a sequence of values that were used to instantiate a Func expression. This is used 553 to check that the provided arguments don't exceed the function argument limit. 554 555 Returns: 556 A list of error messages for all possible errors that were found. 557 """ 558 errors: t.List[str] = [] 559 560 for k in self.args: 561 if k not in self.arg_types: 562 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 563 for k, mandatory in self.arg_types.items(): 564 v = self.args.get(k) 565 if mandatory and (v is None or (isinstance(v, list) and not v)): 566 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 567 568 if ( 569 args 570 and isinstance(self, Func) 571 and len(args) > len(self.arg_types) 572 and not self.is_var_len_args 573 ): 574 errors.append( 575 f"The number of provided arguments ({len(args)}) is greater than " 576 f"the maximum number of supported arguments ({len(self.arg_types)})" 577 ) 578 579 return errors
Checks if this expression is valid (e.g. all mandatory args are set).
Arguments:
- args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:
A list of error messages for all possible errors that were found.
581 def dump(self): 582 """ 583 Dump this Expression to a JSON-serializable dict. 584 """ 585 from sqlglot.serde import dump 586 587 return dump(self)
Dump this Expression to a JSON-serializable dict.
589 @classmethod 590 def load(cls, obj): 591 """ 592 Load a dict (as returned by `Expression.dump`) into an Expression instance. 593 """ 594 from sqlglot.serde import load 595 596 return load(obj)
Load a dict (as returned by Expression.dump) into an Expression instance.
606class Condition(Expression): 607 def and_(self, *expressions, dialect=None, **opts): 608 """ 609 AND this condition with one or multiple expressions. 610 611 Example: 612 >>> condition("x=1").and_("y=1").sql() 613 'x = 1 AND y = 1' 614 615 Args: 616 *expressions (str | Expression): the SQL code strings to parse. 617 If an `Expression` instance is passed, it will be used as-is. 618 dialect (str): the dialect used to parse the input expression. 619 opts (kwargs): other options to use to parse the input expressions. 620 621 Returns: 622 And: the new condition. 623 """ 624 return and_(self, *expressions, dialect=dialect, **opts) 625 626 def or_(self, *expressions, dialect=None, **opts): 627 """ 628 OR this condition with one or multiple expressions. 629 630 Example: 631 >>> condition("x=1").or_("y=1").sql() 632 'x = 1 OR y = 1' 633 634 Args: 635 *expressions (str | Expression): the SQL code strings to parse. 636 If an `Expression` instance is passed, it will be used as-is. 637 dialect (str): the dialect used to parse the input expression. 638 opts (kwargs): other options to use to parse the input expressions. 639 640 Returns: 641 Or: the new condition. 642 """ 643 return or_(self, *expressions, dialect=dialect, **opts) 644 645 def not_(self): 646 """ 647 Wrap this condition with NOT. 648 649 Example: 650 >>> condition("x=1").not_().sql() 651 'NOT x = 1' 652 653 Returns: 654 Not: the new condition. 655 """ 656 return not_(self)
607 def and_(self, *expressions, dialect=None, **opts): 608 """ 609 AND this condition with one or multiple expressions. 610 611 Example: 612 >>> condition("x=1").and_("y=1").sql() 613 'x = 1 AND y = 1' 614 615 Args: 616 *expressions (str | Expression): the SQL code strings to parse. 617 If an `Expression` instance is passed, it will be used as-is. 618 dialect (str): the dialect used to parse the input expression. 619 opts (kwargs): other options to use to parse the input expressions. 620 621 Returns: 622 And: the new condition. 623 """ 624 return and_(self, *expressions, dialect=dialect, **opts)
AND this condition with one or multiple expressions.
Example:
>>> condition("x=1").and_("y=1").sql() 'x = 1 AND y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
And: the new condition.
626 def or_(self, *expressions, dialect=None, **opts): 627 """ 628 OR this condition with one or multiple expressions. 629 630 Example: 631 >>> condition("x=1").or_("y=1").sql() 632 'x = 1 OR y = 1' 633 634 Args: 635 *expressions (str | Expression): the SQL code strings to parse. 636 If an `Expression` instance is passed, it will be used as-is. 637 dialect (str): the dialect used to parse the input expression. 638 opts (kwargs): other options to use to parse the input expressions. 639 640 Returns: 641 Or: the new condition. 642 """ 643 return or_(self, *expressions, dialect=dialect, **opts)
OR this condition with one or multiple expressions.
Example:
>>> condition("x=1").or_("y=1").sql() 'x = 1 OR y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Or: the new condition.
645 def not_(self): 646 """ 647 Wrap this condition with NOT. 648 649 Example: 650 >>> condition("x=1").not_().sql() 651 'NOT x = 1' 652 653 Returns: 654 Not: the new condition. 655 """ 656 return not_(self)
Wrap this condition with NOT.
Example:
>>> condition("x=1").not_().sql() 'NOT x = 1'
Returns:
Not: the new condition.
Inherited Members
Relationships like x = y, x > 1, x >= y.
Inherited Members
663class DerivedTable(Expression): 664 @property 665 def alias_column_names(self): 666 table_alias = self.args.get("alias") 667 if not table_alias: 668 return [] 669 column_list = table_alias.assert_is(TableAlias).args.get("columns") or [] 670 return [c.name for c in column_list] 671 672 @property 673 def selects(self): 674 alias = self.args.get("alias") 675 676 if alias: 677 return alias.columns 678 return [] 679 680 @property 681 def named_selects(self): 682 return [select.output_name for select in self.selects]
Inherited Members
685class Unionable(Expression): 686 def union(self, expression, distinct=True, dialect=None, **opts): 687 """ 688 Builds a UNION expression. 689 690 Example: 691 >>> import sqlglot 692 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 693 'SELECT * FROM foo UNION SELECT * FROM bla' 694 695 Args: 696 expression (str | Expression): the SQL code string. 697 If an `Expression` instance is passed, it will be used as-is. 698 distinct (bool): set the DISTINCT flag if and only if this is true. 699 dialect (str): the dialect used to parse the input expression. 700 opts (kwargs): other options to use to parse the input expressions. 701 Returns: 702 Union: the Union expression. 703 """ 704 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 705 706 def intersect(self, expression, distinct=True, dialect=None, **opts): 707 """ 708 Builds an INTERSECT expression. 709 710 Example: 711 >>> import sqlglot 712 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 713 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 714 715 Args: 716 expression (str | Expression): the SQL code string. 717 If an `Expression` instance is passed, it will be used as-is. 718 distinct (bool): set the DISTINCT flag if and only if this is true. 719 dialect (str): the dialect used to parse the input expression. 720 opts (kwargs): other options to use to parse the input expressions. 721 Returns: 722 Intersect: the Intersect expression 723 """ 724 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 725 726 def except_(self, expression, distinct=True, dialect=None, **opts): 727 """ 728 Builds an EXCEPT expression. 729 730 Example: 731 >>> import sqlglot 732 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 733 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 734 735 Args: 736 expression (str | Expression): the SQL code string. 737 If an `Expression` instance is passed, it will be used as-is. 738 distinct (bool): set the DISTINCT flag if and only if this is true. 739 dialect (str): the dialect used to parse the input expression. 740 opts (kwargs): other options to use to parse the input expressions. 741 Returns: 742 Except: the Except expression 743 """ 744 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
686 def union(self, expression, distinct=True, dialect=None, **opts): 687 """ 688 Builds a UNION expression. 689 690 Example: 691 >>> import sqlglot 692 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 693 'SELECT * FROM foo UNION SELECT * FROM bla' 694 695 Args: 696 expression (str | Expression): the SQL code string. 697 If an `Expression` instance is passed, it will be used as-is. 698 distinct (bool): set the DISTINCT flag if and only if this is true. 699 dialect (str): the dialect used to parse the input expression. 700 opts (kwargs): other options to use to parse the input expressions. 701 Returns: 702 Union: the Union expression. 703 """ 704 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds a UNION expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Union: the Union expression.
706 def intersect(self, expression, distinct=True, dialect=None, **opts): 707 """ 708 Builds an INTERSECT expression. 709 710 Example: 711 >>> import sqlglot 712 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 713 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 714 715 Args: 716 expression (str | Expression): the SQL code string. 717 If an `Expression` instance is passed, it will be used as-is. 718 distinct (bool): set the DISTINCT flag if and only if this is true. 719 dialect (str): the dialect used to parse the input expression. 720 opts (kwargs): other options to use to parse the input expressions. 721 Returns: 722 Intersect: the Intersect expression 723 """ 724 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds an INTERSECT expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Intersect: the Intersect expression
726 def except_(self, expression, distinct=True, dialect=None, **opts): 727 """ 728 Builds an EXCEPT expression. 729 730 Example: 731 >>> import sqlglot 732 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 733 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 734 735 Args: 736 expression (str | Expression): the SQL code string. 737 If an `Expression` instance is passed, it will be used as-is. 738 distinct (bool): set the DISTINCT flag if and only if this is true. 739 dialect (str): the dialect used to parse the input expression. 740 opts (kwargs): other options to use to parse the input expressions. 741 Returns: 742 Except: the Except expression 743 """ 744 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds an EXCEPT expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Except: the Except expression
Inherited Members
Inherited Members
751class Cache(Expression): 752 arg_types = { 753 "with": False, 754 "this": True, 755 "lazy": False, 756 "options": False, 757 "expression": False, 758 }
Inherited Members
Inherited Members
765class Create(Expression): 766 arg_types = { 767 "with": False, 768 "this": True, 769 "kind": True, 770 "expression": False, 771 "set": False, 772 "multiset": False, 773 "global_temporary": False, 774 "volatile": False, 775 "exists": False, 776 "properties": False, 777 "temporary": False, 778 "transient": False, 779 "external": False, 780 "replace": False, 781 "unique": False, 782 "materialized": False, 783 "data": False, 784 "statistics": False, 785 "no_primary_index": False, 786 "indexes": False, 787 "no_schema_binding": False, 788 "begin": False, 789 }
Inherited Members
Inherited Members
Inherited Members
800class SetItem(Expression): 801 arg_types = { 802 "this": False, 803 "expressions": False, 804 "kind": False, 805 "collate": False, # MySQL SET NAMES statement 806 "global": False, 807 }
Inherited Members
810class Show(Expression): 811 arg_types = { 812 "this": True, 813 "target": False, 814 "offset": False, 815 "limit": False, 816 "like": False, 817 "where": False, 818 "db": False, 819 "full": False, 820 "mutex": False, 821 "query": False, 822 "channel": False, 823 "global": False, 824 "log": False, 825 "position": False, 826 "types": False, 827 }
Inherited Members
830class UserDefinedFunction(Expression): 831 arg_types = {"this": True, "expressions": False, "wrapped": False}
Inherited Members
Inherited Members
838class With(Expression): 839 arg_types = {"expressions": True, "recursive": False} 840 841 @property 842 def recursive(self) -> bool: 843 return bool(self.args.get("recursive"))
Inherited Members
Inherited Members
Inherited Members
854class TableAlias(Expression): 855 arg_types = {"this": False, "columns": False} 856 857 @property 858 def columns(self): 859 return self.args.get("columns") or []
Inherited Members
Inherited Members
Inherited Members
Inherited Members
874class Column(Condition): 875 arg_types = {"this": True, "table": False, "db": False, "catalog": False} 876 877 @property 878 def table(self) -> str: 879 return self.text("table") 880 881 @property 882 def db(self) -> str: 883 return self.text("db") 884 885 @property 886 def catalog(self) -> str: 887 return self.text("catalog") 888 889 @property 890 def output_name(self) -> str: 891 return self.name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
894class ColumnDef(Expression): 895 arg_types = { 896 "this": True, 897 "kind": False, 898 "constraints": False, 899 "exists": False, 900 }
Inherited Members
903class AlterColumn(Expression): 904 arg_types = { 905 "this": True, 906 "dtype": False, 907 "collate": False, 908 "using": False, 909 "default": False, 910 "drop": False, 911 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
966class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind): 967 # this: True -> ALWAYS, this: False -> BY DEFAULT 968 arg_types = { 969 "this": False, 970 "start": False, 971 "increment": False, 972 "minvalue": False, 973 "maxvalue": False, 974 "cycle": False, 975 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1010class Delete(Expression): 1011 arg_types = {"with": False, "this": False, "using": False, "where": False}
Inherited Members
1014class Drop(Expression): 1015 arg_types = { 1016 "this": False, 1017 "kind": False, 1018 "exists": False, 1019 "temporary": False, 1020 "materialized": False, 1021 "cascade": False, 1022 }
Inherited Members
Inherited Members
Inherited Members
1033class Directory(Expression): 1034 # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html 1035 arg_types = {"this": True, "local": False, "row_format": False}
Inherited Members
1038class ForeignKey(Expression): 1039 arg_types = { 1040 "expressions": True, 1041 "reference": False, 1042 "delete": False, 1043 "update": False, 1044 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1077class Identifier(Expression): 1078 arg_types = {"this": True, "quoted": False} 1079 1080 @property 1081 def quoted(self): 1082 return bool(self.args.get("quoted")) 1083 1084 def __eq__(self, other): 1085 return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this) 1086 1087 def __hash__(self): 1088 return hash((self.key, self.this.lower())) 1089 1090 @property 1091 def output_name(self): 1092 return self.name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
1095class Index(Expression): 1096 arg_types = { 1097 "this": False, 1098 "table": False, 1099 "where": False, 1100 "columns": False, 1101 "unique": False, 1102 "primary": False, 1103 "amp": False, # teradata 1104 }
Inherited Members
1107class Insert(Expression): 1108 arg_types = { 1109 "with": False, 1110 "this": True, 1111 "expression": False, 1112 "overwrite": False, 1113 "exists": False, 1114 "partition": False, 1115 "alternative": False, 1116 }
Inherited Members
Inherited Members
Inherited Members
1129class LoadData(Expression): 1130 arg_types = { 1131 "this": True, 1132 "local": False, 1133 "overwrite": False, 1134 "inpath": True, 1135 "partition": False, 1136 "input_format": False, 1137 "serde": False, 1138 }
Inherited Members
Inherited Members
Inherited Members
1149class Group(Expression): 1150 arg_types = { 1151 "expressions": False, 1152 "grouping_sets": False, 1153 "cube": False, 1154 "rollup": False, 1155 }
Inherited Members
Inherited Members
Inherited Members
1166class Literal(Condition): 1167 arg_types = {"this": True, "is_string": True} 1168 1169 def __eq__(self, other): 1170 return ( 1171 isinstance(other, Literal) 1172 and self.this == other.this 1173 and self.args["is_string"] == other.args["is_string"] 1174 ) 1175 1176 def __hash__(self): 1177 return hash((self.key, self.this, self.args["is_string"])) 1178 1179 @classmethod 1180 def number(cls, number) -> Literal: 1181 return cls(this=str(number), is_string=False) 1182 1183 @classmethod 1184 def string(cls, string) -> Literal: 1185 return cls(this=str(string), is_string=True) 1186 1187 @property 1188 def output_name(self): 1189 return self.name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
1192class Join(Expression): 1193 arg_types = { 1194 "this": True, 1195 "on": False, 1196 "side": False, 1197 "kind": False, 1198 "using": False, 1199 "natural": False, 1200 } 1201 1202 @property 1203 def kind(self): 1204 return self.text("kind").upper() 1205 1206 @property 1207 def side(self): 1208 return self.text("side").upper() 1209 1210 @property 1211 def alias_or_name(self): 1212 return self.this.alias_or_name 1213 1214 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1215 """ 1216 Append to or set the ON expressions. 1217 1218 Example: 1219 >>> import sqlglot 1220 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1221 'JOIN x ON y = 1' 1222 1223 Args: 1224 *expressions (str | Expression): the SQL code strings to parse. 1225 If an `Expression` instance is passed, it will be used as-is. 1226 Multiple expressions are combined with an AND operator. 1227 append (bool): if `True`, AND the new expressions to any existing expression. 1228 Otherwise, this resets the expression. 1229 dialect (str): the dialect used to parse the input expressions. 1230 copy (bool): if `False`, modify this expression instance in-place. 1231 opts (kwargs): other options to use to parse the input expressions. 1232 1233 Returns: 1234 Join: the modified join expression. 1235 """ 1236 join = _apply_conjunction_builder( 1237 *expressions, 1238 instance=self, 1239 arg="on", 1240 append=append, 1241 dialect=dialect, 1242 copy=copy, 1243 **opts, 1244 ) 1245 1246 if join.kind == "CROSS": 1247 join.set("kind", None) 1248 1249 return join 1250 1251 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1252 """ 1253 Append to or set the USING expressions. 1254 1255 Example: 1256 >>> import sqlglot 1257 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1258 'JOIN x USING (foo, bla)' 1259 1260 Args: 1261 *expressions (str | Expression): the SQL code strings to parse. 1262 If an `Expression` instance is passed, it will be used as-is. 1263 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1264 Otherwise, this resets the expression. 1265 dialect (str): the dialect used to parse the input expressions. 1266 copy (bool): if `False`, modify this expression instance in-place. 1267 opts (kwargs): other options to use to parse the input expressions. 1268 1269 Returns: 1270 Join: the modified join expression. 1271 """ 1272 join = _apply_list_builder( 1273 *expressions, 1274 instance=self, 1275 arg="using", 1276 append=append, 1277 dialect=dialect, 1278 copy=copy, 1279 **opts, 1280 ) 1281 1282 if join.kind == "CROSS": 1283 join.set("kind", None) 1284 1285 return join
1214 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1215 """ 1216 Append to or set the ON expressions. 1217 1218 Example: 1219 >>> import sqlglot 1220 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1221 'JOIN x ON y = 1' 1222 1223 Args: 1224 *expressions (str | Expression): the SQL code strings to parse. 1225 If an `Expression` instance is passed, it will be used as-is. 1226 Multiple expressions are combined with an AND operator. 1227 append (bool): if `True`, AND the new expressions to any existing expression. 1228 Otherwise, this resets the expression. 1229 dialect (str): the dialect used to parse the input expressions. 1230 copy (bool): if `False`, modify this expression instance in-place. 1231 opts (kwargs): other options to use to parse the input expressions. 1232 1233 Returns: 1234 Join: the modified join expression. 1235 """ 1236 join = _apply_conjunction_builder( 1237 *expressions, 1238 instance=self, 1239 arg="on", 1240 append=append, 1241 dialect=dialect, 1242 copy=copy, 1243 **opts, 1244 ) 1245 1246 if join.kind == "CROSS": 1247 join.set("kind", None) 1248 1249 return join
Append to or set the ON expressions.
Example:
>>> import sqlglot >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 'JOIN x ON y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Join: the modified join expression.
1251 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1252 """ 1253 Append to or set the USING expressions. 1254 1255 Example: 1256 >>> import sqlglot 1257 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1258 'JOIN x USING (foo, bla)' 1259 1260 Args: 1261 *expressions (str | Expression): the SQL code strings to parse. 1262 If an `Expression` instance is passed, it will be used as-is. 1263 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1264 Otherwise, this resets the expression. 1265 dialect (str): the dialect used to parse the input expressions. 1266 copy (bool): if `False`, modify this expression instance in-place. 1267 opts (kwargs): other options to use to parse the input expressions. 1268 1269 Returns: 1270 Join: the modified join expression. 1271 """ 1272 join = _apply_list_builder( 1273 *expressions, 1274 instance=self, 1275 arg="using", 1276 append=append, 1277 dialect=dialect, 1278 copy=copy, 1279 **opts, 1280 ) 1281 1282 if join.kind == "CROSS": 1283 join.set("kind", None) 1284 1285 return join
Append to or set the USING expressions.
Example:
>>> import sqlglot >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 'JOIN x USING (foo, bla)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Join: the modified join expression.
Inherited Members
1288class Lateral(UDTF): 1289 arg_types = {"this": True, "view": False, "outer": False, "alias": False}
Inherited Members
1292class MatchRecognize(Expression): 1293 arg_types = { 1294 "partition_by": False, 1295 "order": False, 1296 "measures": False, 1297 "rows": False, 1298 "after": False, 1299 "pattern": False, 1300 "define": False, 1301 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1404class ReturnsProperty(Property): 1405 arg_types = {"this": True, "is_table": False, "table": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1420class RowFormatDelimitedProperty(Property): 1421 # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml 1422 arg_types = { 1423 "fields": False, 1424 "escaped": False, 1425 "collection_items": False, 1426 "map_keys": False, 1427 "lines": False, 1428 "null": False, 1429 "serde": False, 1430 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1457class AfterJournalProperty(Property): 1458 arg_types = {"no": True, "dual": False, "local": False}
Inherited Members
Inherited Members
Inherited Members
1469class MergeBlockRatioProperty(Property): 1470 arg_types = {"this": False, "no": False, "default": False, "percent": False}
Inherited Members
1473class DataBlocksizeProperty(Property): 1474 arg_types = {"size": False, "units": False, "min": False, "default": False}
Inherited Members
1477class BlockCompressionProperty(Property): 1478 arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
Inherited Members
1481class IsolatedLoadingProperty(Property): 1482 arg_types = { 1483 "no": True, 1484 "concurrent": True, 1485 "for_all": True, 1486 "for_insert": True, 1487 "for_none": True, 1488 }
Inherited Members
1491class LockingProperty(Property): 1492 arg_types = { 1493 "this": False, 1494 "kind": True, 1495 "for_or_in": True, 1496 "lock_type": True, 1497 "override": False, 1498 }
Inherited Members
1501class Properties(Expression): 1502 arg_types = {"expressions": True} 1503 1504 NAME_TO_PROPERTY = { 1505 "ALGORITHM": AlgorithmProperty, 1506 "AUTO_INCREMENT": AutoIncrementProperty, 1507 "CHARACTER SET": CharacterSetProperty, 1508 "COLLATE": CollateProperty, 1509 "COMMENT": SchemaCommentProperty, 1510 "DEFINER": DefinerProperty, 1511 "DISTKEY": DistKeyProperty, 1512 "DISTSTYLE": DistStyleProperty, 1513 "ENGINE": EngineProperty, 1514 "EXECUTE AS": ExecuteAsProperty, 1515 "FORMAT": FileFormatProperty, 1516 "LANGUAGE": LanguageProperty, 1517 "LOCATION": LocationProperty, 1518 "PARTITIONED_BY": PartitionedByProperty, 1519 "RETURNS": ReturnsProperty, 1520 "SORTKEY": SortKeyProperty, 1521 "TABLE_FORMAT": TableFormatProperty, 1522 } 1523 1524 PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()} 1525 1526 # CREATE property locations 1527 # Form: schema specified 1528 # create [POST_CREATE] 1529 # table a [POST_NAME] 1530 # (b int) [POST_SCHEMA] 1531 # with ([POST_WITH]) 1532 # index (b) [POST_INDEX] 1533 # 1534 # Form: alias selection 1535 # create [POST_CREATE] 1536 # table a [POST_NAME] 1537 # as [POST_ALIAS] (select * from b) 1538 # index (c) [POST_INDEX] 1539 class Location(AutoName): 1540 POST_CREATE = auto() 1541 POST_NAME = auto() 1542 POST_SCHEMA = auto() 1543 POST_WITH = auto() 1544 POST_ALIAS = auto() 1545 POST_INDEX = auto() 1546 UNSUPPORTED = auto() 1547 1548 @classmethod 1549 def from_dict(cls, properties_dict) -> Properties: 1550 expressions = [] 1551 for key, value in properties_dict.items(): 1552 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1553 if property_cls: 1554 expressions.append(property_cls(this=convert(value))) 1555 else: 1556 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1557 1558 return cls(expressions=expressions)
1548 @classmethod 1549 def from_dict(cls, properties_dict) -> Properties: 1550 expressions = [] 1551 for key, value in properties_dict.items(): 1552 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1553 if property_cls: 1554 expressions.append(property_cls(this=convert(value))) 1555 else: 1556 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1557 1558 return cls(expressions=expressions)
Inherited Members
1539 class Location(AutoName): 1540 POST_CREATE = auto() 1541 POST_NAME = auto() 1542 POST_SCHEMA = auto() 1543 POST_WITH = auto() 1544 POST_ALIAS = auto() 1545 POST_INDEX = auto() 1546 UNSUPPORTED = auto()
An enumeration.
Inherited Members
- enum.Enum
- name
- value
Inherited Members
Inherited Members
1570class Reference(Expression): 1571 arg_types = {"this": True, "expressions": False, "options": False}
Inherited Members
Inherited Members
1578class Subqueryable(Unionable): 1579 def subquery(self, alias=None, copy=True) -> Subquery: 1580 """ 1581 Convert this expression to an aliased expression that can be used as a Subquery. 1582 1583 Example: 1584 >>> subquery = Select().select("x").from_("tbl").subquery() 1585 >>> Select().select("x").from_(subquery).sql() 1586 'SELECT x FROM (SELECT x FROM tbl)' 1587 1588 Args: 1589 alias (str | Identifier): an optional alias for the subquery 1590 copy (bool): if `False`, modify this expression instance in-place. 1591 1592 Returns: 1593 Alias: the subquery 1594 """ 1595 instance = _maybe_copy(self, copy) 1596 return Subquery( 1597 this=instance, 1598 alias=TableAlias(this=to_identifier(alias)), 1599 ) 1600 1601 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1602 raise NotImplementedError 1603 1604 @property 1605 def ctes(self): 1606 with_ = self.args.get("with") 1607 if not with_: 1608 return [] 1609 return with_.expressions 1610 1611 @property 1612 def selects(self): 1613 raise NotImplementedError("Subqueryable objects must implement `selects`") 1614 1615 @property 1616 def named_selects(self): 1617 raise NotImplementedError("Subqueryable objects must implement `named_selects`") 1618 1619 def with_( 1620 self, 1621 alias, 1622 as_, 1623 recursive=None, 1624 append=True, 1625 dialect=None, 1626 copy=True, 1627 **opts, 1628 ): 1629 """ 1630 Append to or set the common table expressions. 1631 1632 Example: 1633 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1634 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1635 1636 Args: 1637 alias (str | Expression): the SQL code string to parse as the table name. 1638 If an `Expression` instance is passed, this is used as-is. 1639 as_ (str | Expression): the SQL code string to parse as the table expression. 1640 If an `Expression` instance is passed, it will be used as-is. 1641 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1642 append (bool): if `True`, add to any existing expressions. 1643 Otherwise, this resets the expressions. 1644 dialect (str): the dialect used to parse the input expression. 1645 copy (bool): if `False`, modify this expression instance in-place. 1646 opts (kwargs): other options to use to parse the input expressions. 1647 1648 Returns: 1649 Select: the modified expression. 1650 """ 1651 alias_expression = maybe_parse( 1652 alias, 1653 dialect=dialect, 1654 into=TableAlias, 1655 **opts, 1656 ) 1657 as_expression = maybe_parse( 1658 as_, 1659 dialect=dialect, 1660 **opts, 1661 ) 1662 cte = CTE( 1663 this=as_expression, 1664 alias=alias_expression, 1665 ) 1666 return _apply_child_list_builder( 1667 cte, 1668 instance=self, 1669 arg="with", 1670 append=append, 1671 copy=copy, 1672 into=With, 1673 properties={"recursive": recursive or False}, 1674 )
1579 def subquery(self, alias=None, copy=True) -> Subquery: 1580 """ 1581 Convert this expression to an aliased expression that can be used as a Subquery. 1582 1583 Example: 1584 >>> subquery = Select().select("x").from_("tbl").subquery() 1585 >>> Select().select("x").from_(subquery).sql() 1586 'SELECT x FROM (SELECT x FROM tbl)' 1587 1588 Args: 1589 alias (str | Identifier): an optional alias for the subquery 1590 copy (bool): if `False`, modify this expression instance in-place. 1591 1592 Returns: 1593 Alias: the subquery 1594 """ 1595 instance = _maybe_copy(self, copy) 1596 return Subquery( 1597 this=instance, 1598 alias=TableAlias(this=to_identifier(alias)), 1599 )
Convert this expression to an aliased expression that can be used as a Subquery.
Example:
>>> subquery = Select().select("x").from_("tbl").subquery() >>> Select().select("x").from_(subquery).sql() 'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
- alias (str | Identifier): an optional alias for the subquery
- copy (bool): if
False, modify this expression instance in-place.
Returns:
Alias: the subquery
1619 def with_( 1620 self, 1621 alias, 1622 as_, 1623 recursive=None, 1624 append=True, 1625 dialect=None, 1626 copy=True, 1627 **opts, 1628 ): 1629 """ 1630 Append to or set the common table expressions. 1631 1632 Example: 1633 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1634 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1635 1636 Args: 1637 alias (str | Expression): the SQL code string to parse as the table name. 1638 If an `Expression` instance is passed, this is used as-is. 1639 as_ (str | Expression): the SQL code string to parse as the table expression. 1640 If an `Expression` instance is passed, it will be used as-is. 1641 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1642 append (bool): if `True`, add to any existing expressions. 1643 Otherwise, this resets the expressions. 1644 dialect (str): the dialect used to parse the input expression. 1645 copy (bool): if `False`, modify this expression instance in-place. 1646 opts (kwargs): other options to use to parse the input expressions. 1647 1648 Returns: 1649 Select: the modified expression. 1650 """ 1651 alias_expression = maybe_parse( 1652 alias, 1653 dialect=dialect, 1654 into=TableAlias, 1655 **opts, 1656 ) 1657 as_expression = maybe_parse( 1658 as_, 1659 dialect=dialect, 1660 **opts, 1661 ) 1662 cte = CTE( 1663 this=as_expression, 1664 alias=alias_expression, 1665 ) 1666 return _apply_child_list_builder( 1667 cte, 1668 instance=self, 1669 arg="with", 1670 append=append, 1671 copy=copy, 1672 into=With, 1673 properties={"recursive": recursive or False}, 1674 )
Append to or set the common table expressions.
Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
- alias (str | Expression): the SQL code string to parse as the table name.
If an
Expressioninstance is passed, this is used as-is. - as_ (str | Expression): the SQL code string to parse as the table expression.
If an
Expressioninstance is passed, it will be used as-is. - recursive (bool): set the RECURSIVE part of the expression. Defaults to
False. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
Inherited Members
1697class Table(Expression): 1698 arg_types = { 1699 "this": True, 1700 "alias": False, 1701 "db": False, 1702 "catalog": False, 1703 "laterals": False, 1704 "joins": False, 1705 "pivots": False, 1706 "hints": False, 1707 "system_time": False, 1708 } 1709 1710 @property 1711 def db(self) -> str: 1712 return self.text("db") 1713 1714 @property 1715 def catalog(self) -> str: 1716 return self.text("catalog")
Inherited Members
1720class SystemTime(Expression): 1721 arg_types = { 1722 "this": False, 1723 "expression": False, 1724 "kind": True, 1725 }
Inherited Members
1728class Union(Subqueryable): 1729 arg_types = { 1730 "with": False, 1731 "this": True, 1732 "expression": True, 1733 "distinct": False, 1734 **QUERY_MODIFIERS, 1735 } 1736 1737 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1738 """ 1739 Set the LIMIT expression. 1740 1741 Example: 1742 >>> select("1").union(select("1")).limit(1).sql() 1743 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1744 1745 Args: 1746 expression (str | int | Expression): the SQL code string to parse. 1747 This can also be an integer. 1748 If a `Limit` instance is passed, this is used as-is. 1749 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1750 dialect (str): the dialect used to parse the input expression. 1751 copy (bool): if `False`, modify this expression instance in-place. 1752 opts (kwargs): other options to use to parse the input expressions. 1753 1754 Returns: 1755 Select: The limited subqueryable. 1756 """ 1757 return ( 1758 select("*") 1759 .from_(self.subquery(alias="_l_0", copy=copy)) 1760 .limit(expression, dialect=dialect, copy=False, **opts) 1761 ) 1762 1763 def select( 1764 self, 1765 *expressions: str | Expression, 1766 append: bool = True, 1767 dialect: DialectType = None, 1768 copy: bool = True, 1769 **opts, 1770 ) -> Union: 1771 """Append to or set the SELECT of the union recursively. 1772 1773 Example: 1774 >>> from sqlglot import parse_one 1775 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1776 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1777 1778 Args: 1779 *expressions: the SQL code strings to parse. 1780 If an `Expression` instance is passed, it will be used as-is. 1781 append: if `True`, add to any existing expressions. 1782 Otherwise, this resets the expressions. 1783 dialect: the dialect used to parse the input expressions. 1784 copy: if `False`, modify this expression instance in-place. 1785 opts: other options to use to parse the input expressions. 1786 1787 Returns: 1788 Union: the modified expression. 1789 """ 1790 this = self.copy() if copy else self 1791 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1792 this.expression.unnest().select( 1793 *expressions, append=append, dialect=dialect, copy=False, **opts 1794 ) 1795 return this 1796 1797 @property 1798 def named_selects(self): 1799 return self.this.unnest().named_selects 1800 1801 @property 1802 def selects(self): 1803 return self.this.unnest().selects 1804 1805 @property 1806 def left(self): 1807 return self.this 1808 1809 @property 1810 def right(self): 1811 return self.expression
1737 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1738 """ 1739 Set the LIMIT expression. 1740 1741 Example: 1742 >>> select("1").union(select("1")).limit(1).sql() 1743 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1744 1745 Args: 1746 expression (str | int | Expression): the SQL code string to parse. 1747 This can also be an integer. 1748 If a `Limit` instance is passed, this is used as-is. 1749 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1750 dialect (str): the dialect used to parse the input expression. 1751 copy (bool): if `False`, modify this expression instance in-place. 1752 opts (kwargs): other options to use to parse the input expressions. 1753 1754 Returns: 1755 Select: The limited subqueryable. 1756 """ 1757 return ( 1758 select("*") 1759 .from_(self.subquery(alias="_l_0", copy=copy)) 1760 .limit(expression, dialect=dialect, copy=False, **opts) 1761 )
Set the LIMIT expression.
Example:
>>> select("1").union(select("1")).limit(1).sql() 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Limitinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aLimit. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: The limited subqueryable.
1763 def select( 1764 self, 1765 *expressions: str | Expression, 1766 append: bool = True, 1767 dialect: DialectType = None, 1768 copy: bool = True, 1769 **opts, 1770 ) -> Union: 1771 """Append to or set the SELECT of the union recursively. 1772 1773 Example: 1774 >>> from sqlglot import parse_one 1775 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1776 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1777 1778 Args: 1779 *expressions: the SQL code strings to parse. 1780 If an `Expression` instance is passed, it will be used as-is. 1781 append: if `True`, add to any existing expressions. 1782 Otherwise, this resets the expressions. 1783 dialect: the dialect used to parse the input expressions. 1784 copy: if `False`, modify this expression instance in-place. 1785 opts: other options to use to parse the input expressions. 1786 1787 Returns: 1788 Union: the modified expression. 1789 """ 1790 this = self.copy() if copy else self 1791 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1792 this.expression.unnest().select( 1793 *expressions, append=append, dialect=dialect, copy=False, **opts 1794 ) 1795 return this
Append to or set the SELECT of the union recursively.
Example:
>>> from sqlglot import parse_one >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
- *expressions: the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append: if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect: the dialect used to parse the input expressions.
- copy: if
False, modify this expression instance in-place. - opts: other options to use to parse the input expressions.
Returns:
Union: the modified expression.
Inherited Members
Inherited Members
Inherited Members
1822class Unnest(UDTF): 1823 arg_types = { 1824 "expressions": True, 1825 "ordinality": False, 1826 "alias": False, 1827 "offset": False, 1828 }
Inherited Members
1831class Update(Expression): 1832 arg_types = { 1833 "with": False, 1834 "this": False, 1835 "expressions": True, 1836 "from": False, 1837 "where": False, 1838 }
Inherited Members
1841class Values(UDTF): 1842 arg_types = { 1843 "expressions": True, 1844 "ordinality": False, 1845 "alias": False, 1846 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1863class Select(Subqueryable): 1864 arg_types = { 1865 "with": False, 1866 "expressions": False, 1867 "hint": False, 1868 "distinct": False, 1869 "into": False, 1870 "from": False, 1871 **QUERY_MODIFIERS, 1872 } 1873 1874 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1875 """ 1876 Set the FROM expression. 1877 1878 Example: 1879 >>> Select().from_("tbl").select("x").sql() 1880 'SELECT x FROM tbl' 1881 1882 Args: 1883 *expressions (str | Expression): the SQL code strings to parse. 1884 If a `From` instance is passed, this is used as-is. 1885 If another `Expression` instance is passed, it will be wrapped in a `From`. 1886 append (bool): if `True`, add to any existing expressions. 1887 Otherwise, this flattens all the `From` expression into a single expression. 1888 dialect (str): the dialect used to parse the input expression. 1889 copy (bool): if `False`, modify this expression instance in-place. 1890 opts (kwargs): other options to use to parse the input expressions. 1891 1892 Returns: 1893 Select: the modified expression. 1894 """ 1895 return _apply_child_list_builder( 1896 *expressions, 1897 instance=self, 1898 arg="from", 1899 append=append, 1900 copy=copy, 1901 prefix="FROM", 1902 into=From, 1903 dialect=dialect, 1904 **opts, 1905 ) 1906 1907 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1908 """ 1909 Set the GROUP BY expression. 1910 1911 Example: 1912 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1913 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1914 1915 Args: 1916 *expressions (str | Expression): the SQL code strings to parse. 1917 If a `Group` instance is passed, this is used as-is. 1918 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1919 If nothing is passed in then a group by is not applied to the expression 1920 append (bool): if `True`, add to any existing expressions. 1921 Otherwise, this flattens all the `Group` expression into a single expression. 1922 dialect (str): the dialect used to parse the input expression. 1923 copy (bool): if `False`, modify this expression instance in-place. 1924 opts (kwargs): other options to use to parse the input expressions. 1925 1926 Returns: 1927 Select: the modified expression. 1928 """ 1929 if not expressions: 1930 return self if not copy else self.copy() 1931 return _apply_child_list_builder( 1932 *expressions, 1933 instance=self, 1934 arg="group", 1935 append=append, 1936 copy=copy, 1937 prefix="GROUP BY", 1938 into=Group, 1939 dialect=dialect, 1940 **opts, 1941 ) 1942 1943 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1944 """ 1945 Set the ORDER BY expression. 1946 1947 Example: 1948 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1949 'SELECT x FROM tbl ORDER BY x DESC' 1950 1951 Args: 1952 *expressions (str | Expression): the SQL code strings to parse. 1953 If a `Group` instance is passed, this is used as-is. 1954 If another `Expression` instance is passed, it will be wrapped in a `Order`. 1955 append (bool): if `True`, add to any existing expressions. 1956 Otherwise, this flattens all the `Order` expression into a single expression. 1957 dialect (str): the dialect used to parse the input expression. 1958 copy (bool): if `False`, modify this expression instance in-place. 1959 opts (kwargs): other options to use to parse the input expressions. 1960 1961 Returns: 1962 Select: the modified expression. 1963 """ 1964 return _apply_child_list_builder( 1965 *expressions, 1966 instance=self, 1967 arg="order", 1968 append=append, 1969 copy=copy, 1970 prefix="ORDER BY", 1971 into=Order, 1972 dialect=dialect, 1973 **opts, 1974 ) 1975 1976 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1977 """ 1978 Set the SORT BY expression. 1979 1980 Example: 1981 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 1982 'SELECT x FROM tbl SORT BY x DESC' 1983 1984 Args: 1985 *expressions (str | Expression): the SQL code strings to parse. 1986 If a `Group` instance is passed, this is used as-is. 1987 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 1988 append (bool): if `True`, add to any existing expressions. 1989 Otherwise, this flattens all the `Order` expression into a single expression. 1990 dialect (str): the dialect used to parse the input expression. 1991 copy (bool): if `False`, modify this expression instance in-place. 1992 opts (kwargs): other options to use to parse the input expressions. 1993 1994 Returns: 1995 Select: the modified expression. 1996 """ 1997 return _apply_child_list_builder( 1998 *expressions, 1999 instance=self, 2000 arg="sort", 2001 append=append, 2002 copy=copy, 2003 prefix="SORT BY", 2004 into=Sort, 2005 dialect=dialect, 2006 **opts, 2007 ) 2008 2009 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2010 """ 2011 Set the CLUSTER BY expression. 2012 2013 Example: 2014 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2015 'SELECT x FROM tbl CLUSTER BY x DESC' 2016 2017 Args: 2018 *expressions (str | Expression): the SQL code strings to parse. 2019 If a `Group` instance is passed, this is used as-is. 2020 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2021 append (bool): if `True`, add to any existing expressions. 2022 Otherwise, this flattens all the `Order` expression into a single expression. 2023 dialect (str): the dialect used to parse the input expression. 2024 copy (bool): if `False`, modify this expression instance in-place. 2025 opts (kwargs): other options to use to parse the input expressions. 2026 2027 Returns: 2028 Select: the modified expression. 2029 """ 2030 return _apply_child_list_builder( 2031 *expressions, 2032 instance=self, 2033 arg="cluster", 2034 append=append, 2035 copy=copy, 2036 prefix="CLUSTER BY", 2037 into=Cluster, 2038 dialect=dialect, 2039 **opts, 2040 ) 2041 2042 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2043 """ 2044 Set the LIMIT expression. 2045 2046 Example: 2047 >>> Select().from_("tbl").select("x").limit(10).sql() 2048 'SELECT x FROM tbl LIMIT 10' 2049 2050 Args: 2051 expression (str | int | Expression): the SQL code string to parse. 2052 This can also be an integer. 2053 If a `Limit` instance is passed, this is used as-is. 2054 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2055 dialect (str): the dialect used to parse the input expression. 2056 copy (bool): if `False`, modify this expression instance in-place. 2057 opts (kwargs): other options to use to parse the input expressions. 2058 2059 Returns: 2060 Select: the modified expression. 2061 """ 2062 return _apply_builder( 2063 expression=expression, 2064 instance=self, 2065 arg="limit", 2066 into=Limit, 2067 prefix="LIMIT", 2068 dialect=dialect, 2069 copy=copy, 2070 **opts, 2071 ) 2072 2073 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2074 """ 2075 Set the OFFSET expression. 2076 2077 Example: 2078 >>> Select().from_("tbl").select("x").offset(10).sql() 2079 'SELECT x FROM tbl OFFSET 10' 2080 2081 Args: 2082 expression (str | int | Expression): the SQL code string to parse. 2083 This can also be an integer. 2084 If a `Offset` instance is passed, this is used as-is. 2085 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2086 dialect (str): the dialect used to parse the input expression. 2087 copy (bool): if `False`, modify this expression instance in-place. 2088 opts (kwargs): other options to use to parse the input expressions. 2089 2090 Returns: 2091 Select: the modified expression. 2092 """ 2093 return _apply_builder( 2094 expression=expression, 2095 instance=self, 2096 arg="offset", 2097 into=Offset, 2098 prefix="OFFSET", 2099 dialect=dialect, 2100 copy=copy, 2101 **opts, 2102 ) 2103 2104 def select( 2105 self, 2106 *expressions: str | Expression, 2107 append: bool = True, 2108 dialect: DialectType = None, 2109 copy: bool = True, 2110 **opts, 2111 ) -> Select: 2112 """ 2113 Append to or set the SELECT expressions. 2114 2115 Example: 2116 >>> Select().select("x", "y").sql() 2117 'SELECT x, y' 2118 2119 Args: 2120 *expressions: the SQL code strings to parse. 2121 If an `Expression` instance is passed, it will be used as-is. 2122 append: if `True`, add to any existing expressions. 2123 Otherwise, this resets the expressions. 2124 dialect: the dialect used to parse the input expressions. 2125 copy: if `False`, modify this expression instance in-place. 2126 opts: other options to use to parse the input expressions. 2127 2128 Returns: 2129 Select: the modified expression. 2130 """ 2131 return _apply_list_builder( 2132 *expressions, 2133 instance=self, 2134 arg="expressions", 2135 append=append, 2136 dialect=dialect, 2137 copy=copy, 2138 **opts, 2139 ) 2140 2141 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2142 """ 2143 Append to or set the LATERAL expressions. 2144 2145 Example: 2146 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2147 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2148 2149 Args: 2150 *expressions (str | Expression): the SQL code strings to parse. 2151 If an `Expression` instance is passed, it will be used as-is. 2152 append (bool): if `True`, add to any existing expressions. 2153 Otherwise, this resets the expressions. 2154 dialect (str): the dialect used to parse the input expressions. 2155 copy (bool): if `False`, modify this expression instance in-place. 2156 opts (kwargs): other options to use to parse the input expressions. 2157 2158 Returns: 2159 Select: the modified expression. 2160 """ 2161 return _apply_list_builder( 2162 *expressions, 2163 instance=self, 2164 arg="laterals", 2165 append=append, 2166 into=Lateral, 2167 prefix="LATERAL VIEW", 2168 dialect=dialect, 2169 copy=copy, 2170 **opts, 2171 ) 2172 2173 def join( 2174 self, 2175 expression, 2176 on=None, 2177 using=None, 2178 append=True, 2179 join_type=None, 2180 join_alias=None, 2181 dialect=None, 2182 copy=True, 2183 **opts, 2184 ) -> Select: 2185 """ 2186 Append to or set the JOIN expressions. 2187 2188 Example: 2189 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2190 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2191 2192 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2193 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2194 2195 Use `join_type` to change the type of join: 2196 2197 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2198 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2199 2200 Args: 2201 expression (str | Expression): the SQL code string to parse. 2202 If an `Expression` instance is passed, it will be used as-is. 2203 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2204 If an `Expression` instance is passed, it will be used as-is. 2205 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2206 If an `Expression` instance is passed, it will be used as-is. 2207 append (bool): if `True`, add to any existing expressions. 2208 Otherwise, this resets the expressions. 2209 join_type (str): If set, alter the parsed join type 2210 dialect (str): the dialect used to parse the input expressions. 2211 copy (bool): if `False`, modify this expression instance in-place. 2212 opts (kwargs): other options to use to parse the input expressions. 2213 2214 Returns: 2215 Select: the modified expression. 2216 """ 2217 parse_args = {"dialect": dialect, **opts} 2218 2219 try: 2220 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2221 except ParseError: 2222 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2223 2224 join = expression if isinstance(expression, Join) else Join(this=expression) 2225 2226 if isinstance(join.this, Select): 2227 join.this.replace(join.this.subquery()) 2228 2229 if join_type: 2230 natural: t.Optional[Token] 2231 side: t.Optional[Token] 2232 kind: t.Optional[Token] 2233 2234 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2235 2236 if natural: 2237 join.set("natural", True) 2238 if side: 2239 join.set("side", side.text) 2240 if kind: 2241 join.set("kind", kind.text) 2242 2243 if on: 2244 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2245 join.set("on", on) 2246 2247 if using: 2248 join = _apply_list_builder( 2249 *ensure_collection(using), 2250 instance=join, 2251 arg="using", 2252 append=append, 2253 copy=copy, 2254 **opts, 2255 ) 2256 2257 if join_alias: 2258 join.set("this", alias_(join.this, join_alias, table=True)) 2259 return _apply_list_builder( 2260 join, 2261 instance=self, 2262 arg="joins", 2263 append=append, 2264 copy=copy, 2265 **opts, 2266 ) 2267 2268 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2269 """ 2270 Append to or set the WHERE expressions. 2271 2272 Example: 2273 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2274 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2275 2276 Args: 2277 *expressions (str | Expression): the SQL code strings to parse. 2278 If an `Expression` instance is passed, it will be used as-is. 2279 Multiple expressions are combined with an AND operator. 2280 append (bool): if `True`, AND the new expressions to any existing expression. 2281 Otherwise, this resets the expression. 2282 dialect (str): the dialect used to parse the input expressions. 2283 copy (bool): if `False`, modify this expression instance in-place. 2284 opts (kwargs): other options to use to parse the input expressions. 2285 2286 Returns: 2287 Select: the modified expression. 2288 """ 2289 return _apply_conjunction_builder( 2290 *expressions, 2291 instance=self, 2292 arg="where", 2293 append=append, 2294 into=Where, 2295 dialect=dialect, 2296 copy=copy, 2297 **opts, 2298 ) 2299 2300 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2301 """ 2302 Append to or set the HAVING expressions. 2303 2304 Example: 2305 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2306 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2307 2308 Args: 2309 *expressions (str | Expression): the SQL code strings to parse. 2310 If an `Expression` instance is passed, it will be used as-is. 2311 Multiple expressions are combined with an AND operator. 2312 append (bool): if `True`, AND the new expressions to any existing expression. 2313 Otherwise, this resets the expression. 2314 dialect (str): the dialect used to parse the input expressions. 2315 copy (bool): if `False`, modify this expression instance in-place. 2316 opts (kwargs): other options to use to parse the input expressions. 2317 2318 Returns: 2319 Select: the modified expression. 2320 """ 2321 return _apply_conjunction_builder( 2322 *expressions, 2323 instance=self, 2324 arg="having", 2325 append=append, 2326 into=Having, 2327 dialect=dialect, 2328 copy=copy, 2329 **opts, 2330 ) 2331 2332 def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2333 return _apply_list_builder( 2334 *expressions, 2335 instance=self, 2336 arg="windows", 2337 append=append, 2338 into=Window, 2339 dialect=dialect, 2340 copy=copy, 2341 **opts, 2342 ) 2343 2344 def distinct(self, distinct=True, copy=True) -> Select: 2345 """ 2346 Set the OFFSET expression. 2347 2348 Example: 2349 >>> Select().from_("tbl").select("x").distinct().sql() 2350 'SELECT DISTINCT x FROM tbl' 2351 2352 Args: 2353 distinct (bool): whether the Select should be distinct 2354 copy (bool): if `False`, modify this expression instance in-place. 2355 2356 Returns: 2357 Select: the modified expression. 2358 """ 2359 instance = _maybe_copy(self, copy) 2360 instance.set("distinct", Distinct() if distinct else None) 2361 return instance 2362 2363 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2364 """ 2365 Convert this expression to a CREATE TABLE AS statement. 2366 2367 Example: 2368 >>> Select().select("*").from_("tbl").ctas("x").sql() 2369 'CREATE TABLE x AS SELECT * FROM tbl' 2370 2371 Args: 2372 table (str | Expression): the SQL code string to parse as the table name. 2373 If another `Expression` instance is passed, it will be used as-is. 2374 properties (dict): an optional mapping of table properties 2375 dialect (str): the dialect used to parse the input table. 2376 copy (bool): if `False`, modify this expression instance in-place. 2377 opts (kwargs): other options to use to parse the input table. 2378 2379 Returns: 2380 Create: the CREATE TABLE AS expression 2381 """ 2382 instance = _maybe_copy(self, copy) 2383 table_expression = maybe_parse( 2384 table, 2385 into=Table, 2386 dialect=dialect, 2387 **opts, 2388 ) 2389 properties_expression = None 2390 if properties: 2391 properties_expression = Properties.from_dict(properties) 2392 2393 return Create( 2394 this=table_expression, 2395 kind="table", 2396 expression=instance, 2397 properties=properties_expression, 2398 ) 2399 2400 def lock(self, update: bool = True, copy: bool = True) -> Select: 2401 """ 2402 Set the locking read mode for this expression. 2403 2404 Examples: 2405 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2406 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2407 2408 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2409 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2410 2411 Args: 2412 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2413 copy: if `False`, modify this expression instance in-place. 2414 2415 Returns: 2416 The modified expression. 2417 """ 2418 2419 inst = _maybe_copy(self, copy) 2420 inst.set("lock", Lock(update=update)) 2421 2422 return inst 2423 2424 @property 2425 def named_selects(self) -> t.List[str]: 2426 return [e.output_name for e in self.expressions if e.alias_or_name] 2427 2428 @property 2429 def selects(self) -> t.List[Expression]: 2430 return self.expressions
1874 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1875 """ 1876 Set the FROM expression. 1877 1878 Example: 1879 >>> Select().from_("tbl").select("x").sql() 1880 'SELECT x FROM tbl' 1881 1882 Args: 1883 *expressions (str | Expression): the SQL code strings to parse. 1884 If a `From` instance is passed, this is used as-is. 1885 If another `Expression` instance is passed, it will be wrapped in a `From`. 1886 append (bool): if `True`, add to any existing expressions. 1887 Otherwise, this flattens all the `From` expression into a single expression. 1888 dialect (str): the dialect used to parse the input expression. 1889 copy (bool): if `False`, modify this expression instance in-place. 1890 opts (kwargs): other options to use to parse the input expressions. 1891 1892 Returns: 1893 Select: the modified expression. 1894 """ 1895 return _apply_child_list_builder( 1896 *expressions, 1897 instance=self, 1898 arg="from", 1899 append=append, 1900 copy=copy, 1901 prefix="FROM", 1902 into=From, 1903 dialect=dialect, 1904 **opts, 1905 )
Set the FROM expression.
Example:
>>> Select().from_("tbl").select("x").sql() 'SELECT x FROM tbl'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Frominstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aFrom. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theFromexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
1907 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1908 """ 1909 Set the GROUP BY expression. 1910 1911 Example: 1912 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1913 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1914 1915 Args: 1916 *expressions (str | Expression): the SQL code strings to parse. 1917 If a `Group` instance is passed, this is used as-is. 1918 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1919 If nothing is passed in then a group by is not applied to the expression 1920 append (bool): if `True`, add to any existing expressions. 1921 Otherwise, this flattens all the `Group` expression into a single expression. 1922 dialect (str): the dialect used to parse the input expression. 1923 copy (bool): if `False`, modify this expression instance in-place. 1924 opts (kwargs): other options to use to parse the input expressions. 1925 1926 Returns: 1927 Select: the modified expression. 1928 """ 1929 if not expressions: 1930 return self if not copy else self.copy() 1931 return _apply_child_list_builder( 1932 *expressions, 1933 instance=self, 1934 arg="group", 1935 append=append, 1936 copy=copy, 1937 prefix="GROUP BY", 1938 into=Group, 1939 dialect=dialect, 1940 **opts, 1941 )
Set the GROUP BY expression.
Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aGroup. If nothing is passed in then a group by is not applied to the expression - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theGroupexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
1943 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1944 """ 1945 Set the ORDER BY expression. 1946 1947 Example: 1948 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1949 'SELECT x FROM tbl ORDER BY x DESC' 1950 1951 Args: 1952 *expressions (str | Expression): the SQL code strings to parse. 1953 If a `Group` instance is passed, this is used as-is. 1954 If another `Expression` instance is passed, it will be wrapped in a `Order`. 1955 append (bool): if `True`, add to any existing expressions. 1956 Otherwise, this flattens all the `Order` expression into a single expression. 1957 dialect (str): the dialect used to parse the input expression. 1958 copy (bool): if `False`, modify this expression instance in-place. 1959 opts (kwargs): other options to use to parse the input expressions. 1960 1961 Returns: 1962 Select: the modified expression. 1963 """ 1964 return _apply_child_list_builder( 1965 *expressions, 1966 instance=self, 1967 arg="order", 1968 append=append, 1969 copy=copy, 1970 prefix="ORDER BY", 1971 into=Order, 1972 dialect=dialect, 1973 **opts, 1974 )
Set the ORDER BY expression.
Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql() 'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aOrder. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
1976 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1977 """ 1978 Set the SORT BY expression. 1979 1980 Example: 1981 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 1982 'SELECT x FROM tbl SORT BY x DESC' 1983 1984 Args: 1985 *expressions (str | Expression): the SQL code strings to parse. 1986 If a `Group` instance is passed, this is used as-is. 1987 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 1988 append (bool): if `True`, add to any existing expressions. 1989 Otherwise, this flattens all the `Order` expression into a single expression. 1990 dialect (str): the dialect used to parse the input expression. 1991 copy (bool): if `False`, modify this expression instance in-place. 1992 opts (kwargs): other options to use to parse the input expressions. 1993 1994 Returns: 1995 Select: the modified expression. 1996 """ 1997 return _apply_child_list_builder( 1998 *expressions, 1999 instance=self, 2000 arg="sort", 2001 append=append, 2002 copy=copy, 2003 prefix="SORT BY", 2004 into=Sort, 2005 dialect=dialect, 2006 **opts, 2007 )
Set the SORT BY expression.
Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 'SELECT x FROM tbl SORT BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aSORT. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2009 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2010 """ 2011 Set the CLUSTER BY expression. 2012 2013 Example: 2014 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2015 'SELECT x FROM tbl CLUSTER BY x DESC' 2016 2017 Args: 2018 *expressions (str | Expression): the SQL code strings to parse. 2019 If a `Group` instance is passed, this is used as-is. 2020 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2021 append (bool): if `True`, add to any existing expressions. 2022 Otherwise, this flattens all the `Order` expression into a single expression. 2023 dialect (str): the dialect used to parse the input expression. 2024 copy (bool): if `False`, modify this expression instance in-place. 2025 opts (kwargs): other options to use to parse the input expressions. 2026 2027 Returns: 2028 Select: the modified expression. 2029 """ 2030 return _apply_child_list_builder( 2031 *expressions, 2032 instance=self, 2033 arg="cluster", 2034 append=append, 2035 copy=copy, 2036 prefix="CLUSTER BY", 2037 into=Cluster, 2038 dialect=dialect, 2039 **opts, 2040 )
Set the CLUSTER BY expression.
Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aCluster. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2042 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2043 """ 2044 Set the LIMIT expression. 2045 2046 Example: 2047 >>> Select().from_("tbl").select("x").limit(10).sql() 2048 'SELECT x FROM tbl LIMIT 10' 2049 2050 Args: 2051 expression (str | int | Expression): the SQL code string to parse. 2052 This can also be an integer. 2053 If a `Limit` instance is passed, this is used as-is. 2054 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2055 dialect (str): the dialect used to parse the input expression. 2056 copy (bool): if `False`, modify this expression instance in-place. 2057 opts (kwargs): other options to use to parse the input expressions. 2058 2059 Returns: 2060 Select: the modified expression. 2061 """ 2062 return _apply_builder( 2063 expression=expression, 2064 instance=self, 2065 arg="limit", 2066 into=Limit, 2067 prefix="LIMIT", 2068 dialect=dialect, 2069 copy=copy, 2070 **opts, 2071 )
Set the LIMIT expression.
Example:
>>> Select().from_("tbl").select("x").limit(10).sql() 'SELECT x FROM tbl LIMIT 10'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Limitinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aLimit. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2073 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2074 """ 2075 Set the OFFSET expression. 2076 2077 Example: 2078 >>> Select().from_("tbl").select("x").offset(10).sql() 2079 'SELECT x FROM tbl OFFSET 10' 2080 2081 Args: 2082 expression (str | int | Expression): the SQL code string to parse. 2083 This can also be an integer. 2084 If a `Offset` instance is passed, this is used as-is. 2085 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2086 dialect (str): the dialect used to parse the input expression. 2087 copy (bool): if `False`, modify this expression instance in-place. 2088 opts (kwargs): other options to use to parse the input expressions. 2089 2090 Returns: 2091 Select: the modified expression. 2092 """ 2093 return _apply_builder( 2094 expression=expression, 2095 instance=self, 2096 arg="offset", 2097 into=Offset, 2098 prefix="OFFSET", 2099 dialect=dialect, 2100 copy=copy, 2101 **opts, 2102 )
Set the OFFSET expression.
Example:
>>> Select().from_("tbl").select("x").offset(10).sql() 'SELECT x FROM tbl OFFSET 10'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Offsetinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aOffset. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2104 def select( 2105 self, 2106 *expressions: str | Expression, 2107 append: bool = True, 2108 dialect: DialectType = None, 2109 copy: bool = True, 2110 **opts, 2111 ) -> Select: 2112 """ 2113 Append to or set the SELECT expressions. 2114 2115 Example: 2116 >>> Select().select("x", "y").sql() 2117 'SELECT x, y' 2118 2119 Args: 2120 *expressions: the SQL code strings to parse. 2121 If an `Expression` instance is passed, it will be used as-is. 2122 append: if `True`, add to any existing expressions. 2123 Otherwise, this resets the expressions. 2124 dialect: the dialect used to parse the input expressions. 2125 copy: if `False`, modify this expression instance in-place. 2126 opts: other options to use to parse the input expressions. 2127 2128 Returns: 2129 Select: the modified expression. 2130 """ 2131 return _apply_list_builder( 2132 *expressions, 2133 instance=self, 2134 arg="expressions", 2135 append=append, 2136 dialect=dialect, 2137 copy=copy, 2138 **opts, 2139 )
Append to or set the SELECT expressions.
Example:
>>> Select().select("x", "y").sql() 'SELECT x, y'
Arguments:
- *expressions: the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append: if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect: the dialect used to parse the input expressions.
- copy: if
False, modify this expression instance in-place. - opts: other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2141 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2142 """ 2143 Append to or set the LATERAL expressions. 2144 2145 Example: 2146 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2147 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2148 2149 Args: 2150 *expressions (str | Expression): the SQL code strings to parse. 2151 If an `Expression` instance is passed, it will be used as-is. 2152 append (bool): if `True`, add to any existing expressions. 2153 Otherwise, this resets the expressions. 2154 dialect (str): the dialect used to parse the input expressions. 2155 copy (bool): if `False`, modify this expression instance in-place. 2156 opts (kwargs): other options to use to parse the input expressions. 2157 2158 Returns: 2159 Select: the modified expression. 2160 """ 2161 return _apply_list_builder( 2162 *expressions, 2163 instance=self, 2164 arg="laterals", 2165 append=append, 2166 into=Lateral, 2167 prefix="LATERAL VIEW", 2168 dialect=dialect, 2169 copy=copy, 2170 **opts, 2171 )
Append to or set the LATERAL expressions.
Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2173 def join( 2174 self, 2175 expression, 2176 on=None, 2177 using=None, 2178 append=True, 2179 join_type=None, 2180 join_alias=None, 2181 dialect=None, 2182 copy=True, 2183 **opts, 2184 ) -> Select: 2185 """ 2186 Append to or set the JOIN expressions. 2187 2188 Example: 2189 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2190 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2191 2192 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2193 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2194 2195 Use `join_type` to change the type of join: 2196 2197 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2198 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2199 2200 Args: 2201 expression (str | Expression): the SQL code string to parse. 2202 If an `Expression` instance is passed, it will be used as-is. 2203 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2204 If an `Expression` instance is passed, it will be used as-is. 2205 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2206 If an `Expression` instance is passed, it will be used as-is. 2207 append (bool): if `True`, add to any existing expressions. 2208 Otherwise, this resets the expressions. 2209 join_type (str): If set, alter the parsed join type 2210 dialect (str): the dialect used to parse the input expressions. 2211 copy (bool): if `False`, modify this expression instance in-place. 2212 opts (kwargs): other options to use to parse the input expressions. 2213 2214 Returns: 2215 Select: the modified expression. 2216 """ 2217 parse_args = {"dialect": dialect, **opts} 2218 2219 try: 2220 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2221 except ParseError: 2222 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2223 2224 join = expression if isinstance(expression, Join) else Join(this=expression) 2225 2226 if isinstance(join.this, Select): 2227 join.this.replace(join.this.subquery()) 2228 2229 if join_type: 2230 natural: t.Optional[Token] 2231 side: t.Optional[Token] 2232 kind: t.Optional[Token] 2233 2234 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2235 2236 if natural: 2237 join.set("natural", True) 2238 if side: 2239 join.set("side", side.text) 2240 if kind: 2241 join.set("kind", kind.text) 2242 2243 if on: 2244 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2245 join.set("on", on) 2246 2247 if using: 2248 join = _apply_list_builder( 2249 *ensure_collection(using), 2250 instance=join, 2251 arg="using", 2252 append=append, 2253 copy=copy, 2254 **opts, 2255 ) 2256 2257 if join_alias: 2258 join.set("this", alias_(join.this, join_alias, table=True)) 2259 return _apply_list_builder( 2260 join, 2261 instance=self, 2262 arg="joins", 2263 append=append, 2264 copy=copy, 2265 **opts, 2266 )
Append to or set the JOIN expressions.
Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 'SELECT 1 FROM a JOIN b USING (x, y, z)'Use
join_typeto change the type of join:>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
- expression (str | Expression): the SQL code string to parse.
If an
Expressioninstance is passed, it will be used as-is. - on (str | Expression): optionally specify the join "on" criteria as a SQL string.
If an
Expressioninstance is passed, it will be used as-is. - using (str | Expression): optionally specify the join "using" criteria as a SQL string.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - join_type (str): If set, alter the parsed join type
- dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2268 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2269 """ 2270 Append to or set the WHERE expressions. 2271 2272 Example: 2273 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2274 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2275 2276 Args: 2277 *expressions (str | Expression): the SQL code strings to parse. 2278 If an `Expression` instance is passed, it will be used as-is. 2279 Multiple expressions are combined with an AND operator. 2280 append (bool): if `True`, AND the new expressions to any existing expression. 2281 Otherwise, this resets the expression. 2282 dialect (str): the dialect used to parse the input expressions. 2283 copy (bool): if `False`, modify this expression instance in-place. 2284 opts (kwargs): other options to use to parse the input expressions. 2285 2286 Returns: 2287 Select: the modified expression. 2288 """ 2289 return _apply_conjunction_builder( 2290 *expressions, 2291 instance=self, 2292 arg="where", 2293 append=append, 2294 into=Where, 2295 dialect=dialect, 2296 copy=copy, 2297 **opts, 2298 )
Append to or set the WHERE expressions.
Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2300 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2301 """ 2302 Append to or set the HAVING expressions. 2303 2304 Example: 2305 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2306 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2307 2308 Args: 2309 *expressions (str | Expression): the SQL code strings to parse. 2310 If an `Expression` instance is passed, it will be used as-is. 2311 Multiple expressions are combined with an AND operator. 2312 append (bool): if `True`, AND the new expressions to any existing expression. 2313 Otherwise, this resets the expression. 2314 dialect (str): the dialect used to parse the input expressions. 2315 copy (bool): if `False`, modify this expression instance in-place. 2316 opts (kwargs): other options to use to parse the input expressions. 2317 2318 Returns: 2319 Select: the modified expression. 2320 """ 2321 return _apply_conjunction_builder( 2322 *expressions, 2323 instance=self, 2324 arg="having", 2325 append=append, 2326 into=Having, 2327 dialect=dialect, 2328 copy=copy, 2329 **opts, 2330 )
Append to or set the HAVING expressions.
Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2344 def distinct(self, distinct=True, copy=True) -> Select: 2345 """ 2346 Set the OFFSET expression. 2347 2348 Example: 2349 >>> Select().from_("tbl").select("x").distinct().sql() 2350 'SELECT DISTINCT x FROM tbl' 2351 2352 Args: 2353 distinct (bool): whether the Select should be distinct 2354 copy (bool): if `False`, modify this expression instance in-place. 2355 2356 Returns: 2357 Select: the modified expression. 2358 """ 2359 instance = _maybe_copy(self, copy) 2360 instance.set("distinct", Distinct() if distinct else None) 2361 return instance
Set the OFFSET expression.
Example:
>>> Select().from_("tbl").select("x").distinct().sql() 'SELECT DISTINCT x FROM tbl'
Arguments:
- distinct (bool): whether the Select should be distinct
- copy (bool): if
False, modify this expression instance in-place.
Returns:
Select: the modified expression.
2363 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2364 """ 2365 Convert this expression to a CREATE TABLE AS statement. 2366 2367 Example: 2368 >>> Select().select("*").from_("tbl").ctas("x").sql() 2369 'CREATE TABLE x AS SELECT * FROM tbl' 2370 2371 Args: 2372 table (str | Expression): the SQL code string to parse as the table name. 2373 If another `Expression` instance is passed, it will be used as-is. 2374 properties (dict): an optional mapping of table properties 2375 dialect (str): the dialect used to parse the input table. 2376 copy (bool): if `False`, modify this expression instance in-place. 2377 opts (kwargs): other options to use to parse the input table. 2378 2379 Returns: 2380 Create: the CREATE TABLE AS expression 2381 """ 2382 instance = _maybe_copy(self, copy) 2383 table_expression = maybe_parse( 2384 table, 2385 into=Table, 2386 dialect=dialect, 2387 **opts, 2388 ) 2389 properties_expression = None 2390 if properties: 2391 properties_expression = Properties.from_dict(properties) 2392 2393 return Create( 2394 this=table_expression, 2395 kind="table", 2396 expression=instance, 2397 properties=properties_expression, 2398 )
Convert this expression to a CREATE TABLE AS statement.
Example:
>>> Select().select("*").from_("tbl").ctas("x").sql() 'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
- table (str | Expression): the SQL code string to parse as the table name.
If another
Expressioninstance is passed, it will be used as-is. - properties (dict): an optional mapping of table properties
- dialect (str): the dialect used to parse the input table.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input table.
Returns:
Create: the CREATE TABLE AS expression
2400 def lock(self, update: bool = True, copy: bool = True) -> Select: 2401 """ 2402 Set the locking read mode for this expression. 2403 2404 Examples: 2405 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2406 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2407 2408 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2409 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2410 2411 Args: 2412 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2413 copy: if `False`, modify this expression instance in-place. 2414 2415 Returns: 2416 The modified expression. 2417 """ 2418 2419 inst = _maybe_copy(self, copy) 2420 inst.set("lock", Lock(update=update)) 2421 2422 return inst
Set the locking read mode for this expression.
Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE">>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
- update: if
True, the locking type will beFOR UPDATE, else it will beFOR SHARE. - copy: if
False, modify this expression instance in-place.
Returns:
The modified expression.
Inherited Members
2433class Subquery(DerivedTable, Unionable): 2434 arg_types = { 2435 "this": True, 2436 "alias": False, 2437 "with": False, 2438 **QUERY_MODIFIERS, 2439 } 2440 2441 def unnest(self): 2442 """ 2443 Returns the first non subquery. 2444 """ 2445 expression = self 2446 while isinstance(expression, Subquery): 2447 expression = expression.this 2448 return expression 2449 2450 @property 2451 def output_name(self): 2452 return self.alias
2441 def unnest(self): 2442 """ 2443 Returns the first non subquery. 2444 """ 2445 expression = self 2446 while isinstance(expression, Subquery): 2447 expression = expression.this 2448 return expression
Returns the first non subquery.
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
2455class TableSample(Expression): 2456 arg_types = { 2457 "this": False, 2458 "method": False, 2459 "bucket_numerator": False, 2460 "bucket_denominator": False, 2461 "bucket_field": False, 2462 "percent": False, 2463 "rows": False, 2464 "size": False, 2465 "seed": False, 2466 }
Inherited Members
2469class Tag(Expression): 2470 """Tags are used for generating arbitrary sql like SELECT <span>x</span>.""" 2471 2472 arg_types = { 2473 "this": False, 2474 "prefix": False, 2475 "postfix": False, 2476 }
Tags are used for generating arbitrary sql like SELECT x.
Inherited Members
2479class Pivot(Expression): 2480 arg_types = { 2481 "this": False, 2482 "expressions": True, 2483 "field": True, 2484 "unpivot": True, 2485 }
Inherited Members
2488class Window(Expression): 2489 arg_types = { 2490 "this": True, 2491 "partition_by": False, 2492 "order": False, 2493 "spec": False, 2494 "alias": False, 2495 }
Inherited Members
2498class WindowSpec(Expression): 2499 arg_types = { 2500 "kind": False, 2501 "start": False, 2502 "start_side": False, 2503 "end": False, 2504 "end_side": False, 2505 }
Inherited Members
Inherited Members
2512class Star(Expression): 2513 arg_types = {"except": False, "replace": False} 2514 2515 @property 2516 def name(self) -> str: 2517 return "*" 2518 2519 @property 2520 def output_name(self): 2521 return self.name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
Inherited Members
Inherited Members
2536class Null(Condition): 2537 arg_types: t.Dict[str, t.Any] = {} 2538 2539 @property 2540 def name(self) -> str: 2541 return "NULL"
Inherited Members
Inherited Members
2548class DataType(Expression): 2549 arg_types = { 2550 "this": True, 2551 "expressions": False, 2552 "nested": False, 2553 "values": False, 2554 "prefix": False, 2555 } 2556 2557 class Type(AutoName): 2558 CHAR = auto() 2559 NCHAR = auto() 2560 VARCHAR = auto() 2561 NVARCHAR = auto() 2562 TEXT = auto() 2563 MEDIUMTEXT = auto() 2564 LONGTEXT = auto() 2565 MEDIUMBLOB = auto() 2566 LONGBLOB = auto() 2567 BINARY = auto() 2568 VARBINARY = auto() 2569 INT = auto() 2570 TINYINT = auto() 2571 SMALLINT = auto() 2572 BIGINT = auto() 2573 FLOAT = auto() 2574 DOUBLE = auto() 2575 DECIMAL = auto() 2576 BOOLEAN = auto() 2577 JSON = auto() 2578 JSONB = auto() 2579 INTERVAL = auto() 2580 TIME = auto() 2581 TIMESTAMP = auto() 2582 TIMESTAMPTZ = auto() 2583 TIMESTAMPLTZ = auto() 2584 DATE = auto() 2585 DATETIME = auto() 2586 ARRAY = auto() 2587 MAP = auto() 2588 UUID = auto() 2589 GEOGRAPHY = auto() 2590 GEOMETRY = auto() 2591 STRUCT = auto() 2592 NULLABLE = auto() 2593 HLLSKETCH = auto() 2594 HSTORE = auto() 2595 SUPER = auto() 2596 SERIAL = auto() 2597 SMALLSERIAL = auto() 2598 BIGSERIAL = auto() 2599 XML = auto() 2600 UNIQUEIDENTIFIER = auto() 2601 MONEY = auto() 2602 SMALLMONEY = auto() 2603 ROWVERSION = auto() 2604 IMAGE = auto() 2605 VARIANT = auto() 2606 OBJECT = auto() 2607 NULL = auto() 2608 UNKNOWN = auto() # Sentinel value, useful for type annotation 2609 2610 TEXT_TYPES = { 2611 Type.CHAR, 2612 Type.NCHAR, 2613 Type.VARCHAR, 2614 Type.NVARCHAR, 2615 Type.TEXT, 2616 } 2617 2618 INTEGER_TYPES = { 2619 Type.INT, 2620 Type.TINYINT, 2621 Type.SMALLINT, 2622 Type.BIGINT, 2623 } 2624 2625 FLOAT_TYPES = { 2626 Type.FLOAT, 2627 Type.DOUBLE, 2628 } 2629 2630 NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES} 2631 2632 TEMPORAL_TYPES = { 2633 Type.TIMESTAMP, 2634 Type.TIMESTAMPTZ, 2635 Type.TIMESTAMPLTZ, 2636 Type.DATE, 2637 Type.DATETIME, 2638 } 2639 2640 @classmethod 2641 def build( 2642 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2643 ) -> DataType: 2644 from sqlglot import parse_one 2645 2646 if isinstance(dtype, str): 2647 if dtype.upper() in cls.Type.__members__: 2648 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2649 else: 2650 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2651 if data_type_exp is None: 2652 raise ValueError(f"Unparsable data type value: {dtype}") 2653 elif isinstance(dtype, DataType.Type): 2654 data_type_exp = DataType(this=dtype) 2655 elif isinstance(dtype, DataType): 2656 return dtype 2657 else: 2658 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2659 return DataType(**{**data_type_exp.args, **kwargs}) 2660 2661 def is_type(self, dtype: DataType.Type) -> bool: 2662 return self.this == dtype
2640 @classmethod 2641 def build( 2642 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2643 ) -> DataType: 2644 from sqlglot import parse_one 2645 2646 if isinstance(dtype, str): 2647 if dtype.upper() in cls.Type.__members__: 2648 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2649 else: 2650 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2651 if data_type_exp is None: 2652 raise ValueError(f"Unparsable data type value: {dtype}") 2653 elif isinstance(dtype, DataType.Type): 2654 data_type_exp = DataType(this=dtype) 2655 elif isinstance(dtype, DataType): 2656 return dtype 2657 else: 2658 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2659 return DataType(**{**data_type_exp.args, **kwargs})
Inherited Members
2557 class Type(AutoName): 2558 CHAR = auto() 2559 NCHAR = auto() 2560 VARCHAR = auto() 2561 NVARCHAR = auto() 2562 TEXT = auto() 2563 MEDIUMTEXT = auto() 2564 LONGTEXT = auto() 2565 MEDIUMBLOB = auto() 2566 LONGBLOB = auto() 2567 BINARY = auto() 2568 VARBINARY = auto() 2569 INT = auto() 2570 TINYINT = auto() 2571 SMALLINT = auto() 2572 BIGINT = auto() 2573 FLOAT = auto() 2574 DOUBLE = auto() 2575 DECIMAL = auto() 2576 BOOLEAN = auto() 2577 JSON = auto() 2578 JSONB = auto() 2579 INTERVAL = auto() 2580 TIME = auto() 2581 TIMESTAMP = auto() 2582 TIMESTAMPTZ = auto() 2583 TIMESTAMPLTZ = auto() 2584 DATE = auto() 2585 DATETIME = auto() 2586 ARRAY = auto() 2587 MAP = auto() 2588 UUID = auto() 2589 GEOGRAPHY = auto() 2590 GEOMETRY = auto() 2591 STRUCT = auto() 2592 NULLABLE = auto() 2593 HLLSKETCH = auto() 2594 HSTORE = auto() 2595 SUPER = auto() 2596 SERIAL = auto() 2597 SMALLSERIAL = auto() 2598 BIGSERIAL = auto() 2599 XML = auto() 2600 UNIQUEIDENTIFIER = auto() 2601 MONEY = auto() 2602 SMALLMONEY = auto() 2603 ROWVERSION = auto() 2604 IMAGE = auto() 2605 VARIANT = auto() 2606 OBJECT = auto() 2607 NULL = auto() 2608 UNKNOWN = auto() # Sentinel value, useful for type annotation
An enumeration.
Inherited Members
- enum.Enum
- name
- value
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2713class AddConstraint(Expression): 2714 arg_types = {"this": False, "expression": False, "enforced": False}
Inherited Members
Inherited Members
2722class Binary(Expression): 2723 arg_types = {"this": True, "expression": True} 2724 2725 @property 2726 def left(self): 2727 return self.this 2728 2729 @property 2730 def right(self): 2731 return self.expression
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Kwarg in special functions like func(kwarg => y).
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2899class Alias(Expression): 2900 arg_types = {"this": True, "alias": False} 2901 2902 @property 2903 def output_name(self): 2904 return self.alias
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
2907class Aliases(Expression): 2908 arg_types = {"this": True, "expressions": True} 2909 2910 @property 2911 def aliases(self): 2912 return self.expressions
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2931class In(Predicate): 2932 arg_types = { 2933 "this": True, 2934 "expressions": False, 2935 "query": False, 2936 "unnest": False, 2937 "field": False, 2938 "is_global": False, 2939 }
Inherited Members
2942class TimeUnit(Expression): 2943 """Automatically converts unit arg into a var.""" 2944 2945 arg_types = {"unit": False} 2946 2947 def __init__(self, **args): 2948 unit = args.get("unit") 2949 if isinstance(unit, Column): 2950 args["unit"] = Var(this=unit.name) 2951 elif isinstance(unit, Week): 2952 unit.set("this", Var(this=unit.this.name)) 2953 super().__init__(**args)
Automatically converts unit arg into a var.
Inherited Members
Inherited Members
Inherited Members
2969class Func(Condition): 2970 """ 2971 The base class for all function expressions. 2972 2973 Attributes: 2974 is_var_len_args (bool): if set to True the last argument defined in arg_types will be 2975 treated as a variable length argument and the argument's value will be stored as a list. 2976 _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) 2977 for this function expression. These values are used to map this node to a name during parsing 2978 as well as to provide the function's name during SQL string generation. By default the SQL 2979 name is set to the expression's class name transformed to snake case. 2980 """ 2981 2982 is_var_len_args = False 2983 2984 @classmethod 2985 def from_arg_list(cls, args): 2986 if cls.is_var_len_args: 2987 all_arg_keys = list(cls.arg_types) 2988 # If this function supports variable length argument treat the last argument as such. 2989 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 2990 num_non_var = len(non_var_len_arg_keys) 2991 2992 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 2993 args_dict[all_arg_keys[-1]] = args[num_non_var:] 2994 else: 2995 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 2996 2997 return cls(**args_dict) 2998 2999 @classmethod 3000 def sql_names(cls): 3001 if cls is Func: 3002 raise NotImplementedError( 3003 "SQL name is only supported by concrete function implementations" 3004 ) 3005 if "_sql_names" not in cls.__dict__: 3006 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3007 return cls._sql_names 3008 3009 @classmethod 3010 def sql_name(cls): 3011 return cls.sql_names()[0] 3012 3013 @classmethod 3014 def default_parser_mappings(cls): 3015 return {name: cls.from_arg_list for name in cls.sql_names()}
The base class for all function expressions.
Attributes:
- is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
- _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
2984 @classmethod 2985 def from_arg_list(cls, args): 2986 if cls.is_var_len_args: 2987 all_arg_keys = list(cls.arg_types) 2988 # If this function supports variable length argument treat the last argument as such. 2989 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 2990 num_non_var = len(non_var_len_arg_keys) 2991 2992 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 2993 args_dict[all_arg_keys[-1]] = args[num_non_var:] 2994 else: 2995 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 2996 2997 return cls(**args_dict)
2999 @classmethod 3000 def sql_names(cls): 3001 if cls is Func: 3002 raise NotImplementedError( 3003 "SQL name is only supported by concrete function implementations" 3004 ) 3005 if "_sql_names" not in cls.__dict__: 3006 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3007 return cls._sql_names
Inherited Members
Inherited Members
Inherited Members
3026class Anonymous(Func): 3027 arg_types = {"this": True, "expressions": False} 3028 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3056class ArrayConcat(Func): 3057 arg_types = {"this": True, "expressions": False} 3058 is_var_len_args = True
Inherited Members
Inherited Members
3065class ArrayFilter(Func): 3066 arg_types = {"this": True, "expression": True} 3067 _sql_names = ["FILTER", "ARRAY_FILTER"]
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3098class Cast(Func): 3099 arg_types = {"this": True, "to": True} 3100 3101 @property 3102 def name(self) -> str: 3103 return self.this.name 3104 3105 @property 3106 def to(self): 3107 return self.args["to"] 3108 3109 @property 3110 def output_name(self): 3111 return self.name 3112 3113 def is_type(self, dtype: DataType.Type) -> bool: 3114 return self.to.is_type(dtype)
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
Inherited Members
Inherited Members
3125class Ceil(Func): 3126 arg_types = {"this": True, "decimals": False} 3127 _sql_names = ["CEIL", "CEILING"]
Inherited Members
3130class Coalesce(Func): 3131 arg_types = {"this": True, "expressions": False} 3132 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3164class DateAdd(Func, TimeUnit): 3165 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3168class DateSub(Func, TimeUnit): 3169 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3172class DateDiff(Func, TimeUnit): 3173 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
3180class DatetimeAdd(Func, TimeUnit): 3181 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3184class DatetimeSub(Func, TimeUnit): 3185 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3188class DatetimeDiff(Func, TimeUnit): 3189 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3192class DatetimeTrunc(Func, TimeUnit): 3193 arg_types = {"this": True, "unit": True, "zone": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3220class TimestampAdd(Func, TimeUnit): 3221 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3224class TimestampSub(Func, TimeUnit): 3225 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3228class TimestampDiff(Func, TimeUnit): 3229 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3232class TimestampTrunc(Func, TimeUnit): 3233 arg_types = {"this": True, "unit": True, "zone": False}
Inherited Members
3236class TimeAdd(Func, TimeUnit): 3237 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3240class TimeSub(Func, TimeUnit): 3241 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3244class TimeDiff(Func, TimeUnit): 3245 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
3252class DateFromParts(Func): 3253 _sql_names = ["DATEFROMPARTS"] 3254 arg_types = {"year": True, "month": True, "day": True}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3297class Greatest(Func): 3298 arg_types = {"this": True, "expressions": False} 3299 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3314class IfNull(Func): 3315 arg_types = {"this": True, "expression": False} 3316 _sql_names = ["IFNULL", "NVL"]
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3343class Least(Func): 3344 arg_types = {"this": True, "expressions": False} 3345 is_var_len_args = True
Inherited Members
Inherited Members
3352class Levenshtein(Func): 3353 arg_types = { 3354 "this": True, 3355 "expression": False, 3356 "ins_cost": False, 3357 "del_cost": False, 3358 "sub_cost": False, 3359 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3395class Matches(Func): 3396 """Oracle/Snowflake decode. 3397 https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm 3398 Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else) 3399 """ 3400 3401 arg_types = {"this": True, "expressions": True} 3402 is_var_len_args = True
Oracle/Snowflake decode. https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3451class ApproxQuantile(Quantile): 3452 arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
Inherited Members
3455class ReadCSV(Func): 3456 _sql_names = ["READ_CSV"] 3457 is_var_len_args = True 3458 arg_types = {"this": True, "expressions": False}
Inherited Members
3461class Reduce(Func): 3462 arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
Inherited Members
3465class RegexpExtract(Func): 3466 arg_types = { 3467 "this": True, 3468 "expression": True, 3469 "position": False, 3470 "occurrence": False, 3471 "group": False, 3472 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3521class StrPosition(Func): 3522 arg_types = { 3523 "this": True, 3524 "substr": True, 3525 "position": False, 3526 "instance": False, 3527 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3601class Trim(Func): 3602 arg_types = { 3603 "this": True, 3604 "expression": False, 3605 "position": False, 3606 "collation": False, 3607 }
Inherited Members
3610class TsOrDsAdd(Func, TimeUnit): 3611 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3636class UnixToTime(Func): 3637 arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False} 3638 3639 SECONDS = Literal.string("seconds") 3640 MILLIS = Literal.string("millis") 3641 MICROS = Literal.string("micros")
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3664class XMLTable(Func): 3665 arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
Inherited Members
Inherited Members
Inherited Members
3676class Merge(Expression): 3677 arg_types = {"this": True, "using": True, "on": True, "expressions": True}
Inherited Members
Inherited Members
3709def maybe_parse( 3710 sql_or_expression: str | Expression, 3711 *, 3712 into: t.Optional[IntoType] = None, 3713 dialect: DialectType = None, 3714 prefix: t.Optional[str] = None, 3715 copy: bool = False, 3716 **opts, 3717) -> Expression: 3718 """Gracefully handle a possible string or expression. 3719 3720 Example: 3721 >>> maybe_parse("1") 3722 (LITERAL this: 1, is_string: False) 3723 >>> maybe_parse(to_identifier("x")) 3724 (IDENTIFIER this: x, quoted: False) 3725 3726 Args: 3727 sql_or_expression: the SQL code string or an expression 3728 into: the SQLGlot Expression to parse into 3729 dialect: the dialect used to parse the input expressions (in the case that an 3730 input expression is a SQL string). 3731 prefix: a string to prefix the sql with before it gets parsed 3732 (automatically includes a space) 3733 copy: whether or not to copy the expression. 3734 **opts: other options to use to parse the input expressions (again, in the case 3735 that an input expression is a SQL string). 3736 3737 Returns: 3738 Expression: the parsed or given expression. 3739 """ 3740 if isinstance(sql_or_expression, Expression): 3741 if copy: 3742 return sql_or_expression.copy() 3743 return sql_or_expression 3744 3745 import sqlglot 3746 3747 sql = str(sql_or_expression) 3748 if prefix: 3749 sql = f"{prefix} {sql}" 3750 return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
Gracefully handle a possible string or expression.
Example:
>>> maybe_parse("1") (LITERAL this: 1, is_string: False) >>> maybe_parse(to_identifier("x")) (IDENTIFIER this: x, quoted: False)
Arguments:
- sql_or_expression: the SQL code string or an expression
- into: the SQLGlot Expression to parse into
- dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
- prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
- copy: whether or not to copy the expression.
- **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:
Expression: the parsed or given expression.
3896def union(left, right, distinct=True, dialect=None, **opts): 3897 """ 3898 Initializes a syntax tree from one UNION expression. 3899 3900 Example: 3901 >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 3902 'SELECT * FROM foo UNION SELECT * FROM bla' 3903 3904 Args: 3905 left (str | Expression): the SQL code string corresponding to the left-hand side. 3906 If an `Expression` instance is passed, it will be used as-is. 3907 right (str | Expression): the SQL code string corresponding to the right-hand side. 3908 If an `Expression` instance is passed, it will be used as-is. 3909 distinct (bool): set the DISTINCT flag if and only if this is true. 3910 dialect (str): the dialect used to parse the input expression. 3911 opts (kwargs): other options to use to parse the input expressions. 3912 Returns: 3913 Union: the syntax tree for the UNION expression. 3914 """ 3915 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3916 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3917 3918 return Union(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one UNION expression.
Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Union: the syntax tree for the UNION expression.
3921def intersect(left, right, distinct=True, dialect=None, **opts): 3922 """ 3923 Initializes a syntax tree from one INTERSECT expression. 3924 3925 Example: 3926 >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 3927 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 3928 3929 Args: 3930 left (str | Expression): the SQL code string corresponding to the left-hand side. 3931 If an `Expression` instance is passed, it will be used as-is. 3932 right (str | Expression): the SQL code string corresponding to the right-hand side. 3933 If an `Expression` instance is passed, it will be used as-is. 3934 distinct (bool): set the DISTINCT flag if and only if this is true. 3935 dialect (str): the dialect used to parse the input expression. 3936 opts (kwargs): other options to use to parse the input expressions. 3937 Returns: 3938 Intersect: the syntax tree for the INTERSECT expression. 3939 """ 3940 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3941 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3942 3943 return Intersect(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one INTERSECT expression.
Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Intersect: the syntax tree for the INTERSECT expression.
3946def except_(left, right, distinct=True, dialect=None, **opts): 3947 """ 3948 Initializes a syntax tree from one EXCEPT expression. 3949 3950 Example: 3951 >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 3952 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 3953 3954 Args: 3955 left (str | Expression): the SQL code string corresponding to the left-hand side. 3956 If an `Expression` instance is passed, it will be used as-is. 3957 right (str | Expression): the SQL code string corresponding to the right-hand side. 3958 If an `Expression` instance is passed, it will be used as-is. 3959 distinct (bool): set the DISTINCT flag if and only if this is true. 3960 dialect (str): the dialect used to parse the input expression. 3961 opts (kwargs): other options to use to parse the input expressions. 3962 Returns: 3963 Except: the syntax tree for the EXCEPT statement. 3964 """ 3965 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3966 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3967 3968 return Except(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one EXCEPT expression.
Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Except: the syntax tree for the EXCEPT statement.
3971def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select: 3972 """ 3973 Initializes a syntax tree from one or multiple SELECT expressions. 3974 3975 Example: 3976 >>> select("col1", "col2").from_("tbl").sql() 3977 'SELECT col1, col2 FROM tbl' 3978 3979 Args: 3980 *expressions: the SQL code string to parse as the expressions of a 3981 SELECT statement. If an Expression instance is passed, this is used as-is. 3982 dialect: the dialect used to parse the input expressions (in the case that an 3983 input expression is a SQL string). 3984 **opts: other options to use to parse the input expressions (again, in the case 3985 that an input expression is a SQL string). 3986 3987 Returns: 3988 Select: the syntax tree for the SELECT statement. 3989 """ 3990 return Select().select(*expressions, dialect=dialect, **opts)
Initializes a syntax tree from one or multiple SELECT expressions.
Example:
>>> select("col1", "col2").from_("tbl").sql() 'SELECT col1, col2 FROM tbl'
Arguments:
- *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
- dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:
Select: the syntax tree for the SELECT statement.
3993def from_(*expressions, dialect=None, **opts) -> Select: 3994 """ 3995 Initializes a syntax tree from a FROM expression. 3996 3997 Example: 3998 >>> from_("tbl").select("col1", "col2").sql() 3999 'SELECT col1, col2 FROM tbl' 4000 4001 Args: 4002 *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a 4003 SELECT statement. If an Expression instance is passed, this is used as-is. 4004 dialect (str): the dialect used to parse the input expression (in the case that the 4005 input expression is a SQL string). 4006 **opts: other options to use to parse the input expressions (again, in the case 4007 that the input expression is a SQL string). 4008 4009 Returns: 4010 Select: the syntax tree for the SELECT statement. 4011 """ 4012 return Select().from_(*expressions, dialect=dialect, **opts)
Initializes a syntax tree from a FROM expression.
Example:
>>> from_("tbl").select("col1", "col2").sql() 'SELECT col1, col2 FROM tbl'
Arguments:
- *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:
Select: the syntax tree for the SELECT statement.
4015def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update: 4016 """ 4017 Creates an update statement. 4018 4019 Example: 4020 >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() 4021 "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1" 4022 4023 Args: 4024 *properties (Dict[str, Any]): dictionary of properties to set which are 4025 auto converted to sql objects eg None -> NULL 4026 where (str): sql conditional parsed into a WHERE statement 4027 from_ (str): sql statement parsed into a FROM statement 4028 dialect (str): the dialect used to parse the input expressions. 4029 **opts: other options to use to parse the input expressions. 4030 4031 Returns: 4032 Update: the syntax tree for the UPDATE statement. 4033 """ 4034 update = Update(this=maybe_parse(table, into=Table, dialect=dialect)) 4035 update.set( 4036 "expressions", 4037 [ 4038 EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v)) 4039 for k, v in properties.items() 4040 ], 4041 ) 4042 if from_: 4043 update.set( 4044 "from", 4045 maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts), 4046 ) 4047 if isinstance(where, Condition): 4048 where = Where(this=where) 4049 if where: 4050 update.set( 4051 "where", 4052 maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4053 ) 4054 return update
Creates an update statement.
Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
- *properties (Dict[str, Any]): dictionary of properties to set which are auto converted to sql objects eg None -> NULL
- where (str): sql conditional parsed into a WHERE statement
- from_ (str): sql statement parsed into a FROM statement
- dialect (str): the dialect used to parse the input expressions.
- **opts: other options to use to parse the input expressions.
Returns:
Update: the syntax tree for the UPDATE statement.
4057def delete(table, where=None, dialect=None, **opts) -> Delete: 4058 """ 4059 Builds a delete statement. 4060 4061 Example: 4062 >>> delete("my_table", where="id > 1").sql() 4063 'DELETE FROM my_table WHERE id > 1' 4064 4065 Args: 4066 where (str|Condition): sql conditional parsed into a WHERE statement 4067 dialect (str): the dialect used to parse the input expressions. 4068 **opts: other options to use to parse the input expressions. 4069 4070 Returns: 4071 Delete: the syntax tree for the DELETE statement. 4072 """ 4073 return Delete( 4074 this=maybe_parse(table, into=Table, dialect=dialect, **opts), 4075 where=Where(this=where) 4076 if isinstance(where, Condition) 4077 else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4078 )
Builds a delete statement.
Example:
>>> delete("my_table", where="id > 1").sql() 'DELETE FROM my_table WHERE id > 1'
Arguments:
- where (str|Condition): sql conditional parsed into a WHERE statement
- dialect (str): the dialect used to parse the input expressions.
- **opts: other options to use to parse the input expressions.
Returns:
Delete: the syntax tree for the DELETE statement.
4081def condition(expression, dialect=None, **opts) -> Condition: 4082 """ 4083 Initialize a logical condition expression. 4084 4085 Example: 4086 >>> condition("x=1").sql() 4087 'x = 1' 4088 4089 This is helpful for composing larger logical syntax trees: 4090 >>> where = condition("x=1") 4091 >>> where = where.and_("y=1") 4092 >>> Select().from_("tbl").select("*").where(where).sql() 4093 'SELECT * FROM tbl WHERE x = 1 AND y = 1' 4094 4095 Args: 4096 *expression (str | Expression): the SQL code string to parse. 4097 If an Expression instance is passed, this is used as-is. 4098 dialect (str): the dialect used to parse the input expression (in the case that the 4099 input expression is a SQL string). 4100 **opts: other options to use to parse the input expressions (again, in the case 4101 that the input expression is a SQL string). 4102 4103 Returns: 4104 Condition: the expression 4105 """ 4106 return maybe_parse( # type: ignore 4107 expression, 4108 into=Condition, 4109 dialect=dialect, 4110 **opts, 4111 )
Initialize a logical condition expression.
Example:
>>> condition("x=1").sql() 'x = 1'This is helpful for composing larger logical syntax trees:
>>> where = condition("x=1") >>> where = where.and_("y=1") >>> Select().from_("tbl").select("*").where(where).sql() 'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
- *expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:
Condition: the expression
4114def and_(*expressions, dialect=None, **opts) -> And: 4115 """ 4116 Combine multiple conditions with an AND logical operator. 4117 4118 Example: 4119 >>> and_("x=1", and_("y=1", "z=1")).sql() 4120 'x = 1 AND (y = 1 AND z = 1)' 4121 4122 Args: 4123 *expressions (str | Expression): the SQL code strings to parse. 4124 If an Expression instance is passed, this is used as-is. 4125 dialect (str): the dialect used to parse the input expression. 4126 **opts: other options to use to parse the input expressions. 4127 4128 Returns: 4129 And: the new condition 4130 """ 4131 return _combine(expressions, And, dialect, **opts)
Combine multiple conditions with an AND logical operator.
Example:
>>> and_("x=1", and_("y=1", "z=1")).sql() 'x = 1 AND (y = 1 AND z = 1)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
And: the new condition
4134def or_(*expressions, dialect=None, **opts) -> Or: 4135 """ 4136 Combine multiple conditions with an OR logical operator. 4137 4138 Example: 4139 >>> or_("x=1", or_("y=1", "z=1")).sql() 4140 'x = 1 OR (y = 1 OR z = 1)' 4141 4142 Args: 4143 *expressions (str | Expression): the SQL code strings to parse. 4144 If an Expression instance is passed, this is used as-is. 4145 dialect (str): the dialect used to parse the input expression. 4146 **opts: other options to use to parse the input expressions. 4147 4148 Returns: 4149 Or: the new condition 4150 """ 4151 return _combine(expressions, Or, dialect, **opts)
Combine multiple conditions with an OR logical operator.
Example:
>>> or_("x=1", or_("y=1", "z=1")).sql() 'x = 1 OR (y = 1 OR z = 1)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Or: the new condition
4154def not_(expression, dialect=None, **opts) -> Not: 4155 """ 4156 Wrap a condition with a NOT operator. 4157 4158 Example: 4159 >>> not_("this_suit='black'").sql() 4160 "NOT this_suit = 'black'" 4161 4162 Args: 4163 expression (str | Expression): the SQL code strings to parse. 4164 If an Expression instance is passed, this is used as-is. 4165 dialect (str): the dialect used to parse the input expression. 4166 **opts: other options to use to parse the input expressions. 4167 4168 Returns: 4169 Not: the new condition 4170 """ 4171 this = condition( 4172 expression, 4173 dialect=dialect, 4174 **opts, 4175 ) 4176 return Not(this=_wrap_operator(this))
Wrap a condition with a NOT operator.
Example:
>>> not_("this_suit='black'").sql() "NOT this_suit = 'black'"
Arguments:
- expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Not: the new condition
4196def to_identifier(name, quoted=None): 4197 """Builds an identifier. 4198 4199 Args: 4200 name: The name to turn into an identifier. 4201 quoted: Whether or not force quote the identifier. 4202 4203 Returns: 4204 The identifier ast node. 4205 """ 4206 4207 if name is None: 4208 return None 4209 4210 if isinstance(name, Identifier): 4211 identifier = name 4212 elif isinstance(name, str): 4213 identifier = Identifier( 4214 this=name, 4215 quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted, 4216 ) 4217 else: 4218 raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}") 4219 return identifier
Builds an identifier.
Arguments:
- name: The name to turn into an identifier.
- quoted: Whether or not force quote the identifier.
Returns:
The identifier ast node.
4225def to_interval(interval: str | Literal) -> Interval: 4226 """Builds an interval expression from a string like '1 day' or '5 months'.""" 4227 if isinstance(interval, Literal): 4228 if not interval.is_string: 4229 raise ValueError("Invalid interval string.") 4230 4231 interval = interval.this 4232 4233 interval_parts = INTERVAL_STRING_RE.match(interval) # type: ignore 4234 4235 if not interval_parts: 4236 raise ValueError("Invalid interval string.") 4237 4238 return Interval( 4239 this=Literal.string(interval_parts.group(1)), 4240 unit=Var(this=interval_parts.group(2)), 4241 )
Builds an interval expression from a string like '1 day' or '5 months'.
4254def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]: 4255 """ 4256 Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional. 4257 If a table is passed in then that table is returned. 4258 4259 Args: 4260 sql_path: a `[catalog].[schema].[table]` string. 4261 4262 Returns: 4263 A table expression. 4264 """ 4265 if sql_path is None or isinstance(sql_path, Table): 4266 return sql_path 4267 if not isinstance(sql_path, str): 4268 raise ValueError(f"Invalid type provided for a table: {type(sql_path)}") 4269 4270 catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3)) 4271 return Table(this=table_name, db=db, catalog=catalog, **kwargs)
Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional.
If a table is passed in then that table is returned.
Arguments:
- sql_path: a
[catalog].[schema].[table]string.
Returns:
A table expression.
4274def to_column(sql_path: str | Column, **kwargs) -> Column: 4275 """ 4276 Create a column from a `[table].[column]` sql path. Schema is optional. 4277 4278 If a column is passed in then that column is returned. 4279 4280 Args: 4281 sql_path: `[table].[column]` string 4282 Returns: 4283 Table: A column expression 4284 """ 4285 if sql_path is None or isinstance(sql_path, Column): 4286 return sql_path 4287 if not isinstance(sql_path, str): 4288 raise ValueError(f"Invalid type provided for column: {type(sql_path)}") 4289 table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2)) 4290 return Column(this=column_name, table=table_name, **kwargs)
Create a column from a [table].[column] sql path. Schema is optional.
If a column is passed in then that column is returned.
Arguments:
- sql_path:
[table].[column]string
Returns:
Table: A column expression
4293def alias_( 4294 expression: str | Expression, 4295 alias: str | Identifier, 4296 table: bool | t.Sequence[str | Identifier] = False, 4297 quoted: t.Optional[bool] = None, 4298 dialect: DialectType = None, 4299 **opts, 4300): 4301 """Create an Alias expression. 4302 4303 Example: 4304 >>> alias_('foo', 'bar').sql() 4305 'foo AS bar' 4306 4307 >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() 4308 '(SELECT 1, 2) AS bar(a, b)' 4309 4310 Args: 4311 expression: the SQL code strings to parse. 4312 If an Expression instance is passed, this is used as-is. 4313 alias: the alias name to use. If the name has 4314 special characters it is quoted. 4315 table: Whether or not to create a table alias, can also be a list of columns. 4316 quoted: whether or not to quote the alias 4317 dialect: the dialect used to parse the input expression. 4318 **opts: other options to use to parse the input expressions. 4319 4320 Returns: 4321 Alias: the aliased expression 4322 """ 4323 exp = maybe_parse(expression, dialect=dialect, **opts) 4324 alias = to_identifier(alias, quoted=quoted) 4325 4326 if table: 4327 table_alias = TableAlias(this=alias) 4328 exp.set("alias", table_alias) 4329 4330 if not isinstance(table, bool): 4331 for column in table: 4332 table_alias.append("columns", to_identifier(column, quoted=quoted)) 4333 4334 return exp 4335 4336 # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in 4337 # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node 4338 # for the complete Window expression. 4339 # 4340 # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls 4341 4342 if "alias" in exp.arg_types and not isinstance(exp, Window): 4343 exp = exp.copy() 4344 exp.set("alias", alias) 4345 return exp 4346 return Alias(this=exp, alias=alias)
Create an Alias expression.
Example:
>>> alias_('foo', 'bar').sql() 'foo AS bar'>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() '(SELECT 1, 2) AS bar(a, b)'
Arguments:
- expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- alias: the alias name to use. If the name has special characters it is quoted.
- table: Whether or not to create a table alias, can also be a list of columns.
- quoted: whether or not to quote the alias
- dialect: the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Alias: the aliased expression
4349def subquery(expression, alias=None, dialect=None, **opts): 4350 """ 4351 Build a subquery expression. 4352 4353 Example: 4354 >>> subquery('select x from tbl', 'bar').select('x').sql() 4355 'SELECT x FROM (SELECT x FROM tbl) AS bar' 4356 4357 Args: 4358 expression (str | Expression): the SQL code strings to parse. 4359 If an Expression instance is passed, this is used as-is. 4360 alias (str | Expression): the alias name to use. 4361 dialect (str): the dialect used to parse the input expression. 4362 **opts: other options to use to parse the input expressions. 4363 4364 Returns: 4365 Select: a new select with the subquery expression included 4366 """ 4367 4368 expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias) 4369 return Select().from_(expression, dialect=dialect, **opts)
Build a subquery expression.
Example:
>>> subquery('select x from tbl', 'bar').select('x').sql() 'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
- expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- alias (str | Expression): the alias name to use.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Select: a new select with the subquery expression included
4372def column( 4373 col: str | Identifier, 4374 table: t.Optional[str | Identifier] = None, 4375 schema: t.Optional[str | Identifier] = None, 4376 quoted: t.Optional[bool] = None, 4377) -> Column: 4378 """ 4379 Build a Column. 4380 4381 Args: 4382 col: column name 4383 table: table name 4384 schema: schema name 4385 quoted: whether or not to force quote each part 4386 Returns: 4387 Column: column instance 4388 """ 4389 return Column( 4390 this=to_identifier(col, quoted=quoted), 4391 table=to_identifier(table, quoted=quoted), 4392 schema=to_identifier(schema, quoted=quoted), 4393 )
Build a Column.
Arguments:
- col: column name
- table: table name
- schema: schema name
- quoted: whether or not to force quote each part
Returns:
Column: column instance
4396def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast: 4397 """Cast an expression to a data type. 4398 4399 Example: 4400 >>> cast('x + 1', 'int').sql() 4401 'CAST(x + 1 AS INT)' 4402 4403 Args: 4404 expression: The expression to cast. 4405 to: The datatype to cast to. 4406 4407 Returns: 4408 A cast node. 4409 """ 4410 expression = maybe_parse(expression, **opts) 4411 return Cast(this=expression, to=DataType.build(to, **opts))
Cast an expression to a data type.
Example:
>>> cast('x + 1', 'int').sql() 'CAST(x + 1 AS INT)'
Arguments:
- expression: The expression to cast.
- to: The datatype to cast to.
Returns:
A cast node.
4414def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table: 4415 """Build a Table. 4416 4417 Args: 4418 table (str | Expression): column name 4419 db (str | Expression): db name 4420 catalog (str | Expression): catalog name 4421 4422 Returns: 4423 Table: table instance 4424 """ 4425 return Table( 4426 this=to_identifier(table, quoted=quoted), 4427 db=to_identifier(db, quoted=quoted), 4428 catalog=to_identifier(catalog, quoted=quoted), 4429 alias=TableAlias(this=to_identifier(alias)) if alias else None, 4430 )
Build a Table.
Arguments:
- table (str | Expression): column name
- db (str | Expression): db name
- catalog (str | Expression): catalog name
Returns:
Table: table instance
4433def values( 4434 values: t.Iterable[t.Tuple[t.Any, ...]], 4435 alias: t.Optional[str] = None, 4436 columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None, 4437) -> Values: 4438 """Build VALUES statement. 4439 4440 Example: 4441 >>> values([(1, '2')]).sql() 4442 "VALUES (1, '2')" 4443 4444 Args: 4445 values: values statements that will be converted to SQL 4446 alias: optional alias 4447 columns: Optional list of ordered column names or ordered dictionary of column names to types. 4448 If either are provided then an alias is also required. 4449 If a dictionary is provided then the first column of the values will be casted to the expected type 4450 in order to help with type inference. 4451 4452 Returns: 4453 Values: the Values expression object 4454 """ 4455 if columns and not alias: 4456 raise ValueError("Alias is required when providing columns") 4457 table_alias = ( 4458 TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns]) 4459 if columns 4460 else TableAlias(this=to_identifier(alias) if alias else None) 4461 ) 4462 expressions = [convert(tup) for tup in values] 4463 if columns and isinstance(columns, dict): 4464 types = list(columns.values()) 4465 expressions[0].set( 4466 "expressions", 4467 [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)], 4468 ) 4469 return Values( 4470 expressions=expressions, 4471 alias=table_alias, 4472 )
Build VALUES statement.
Example:
>>> values([(1, '2')]).sql() "VALUES (1, '2')"
Arguments:
- values: values statements that will be converted to SQL
- alias: optional alias
- columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required. If a dictionary is provided then the first column of the values will be casted to the expected type in order to help with type inference.
Returns:
Values: the Values expression object
4475def var(name: t.Optional[str | Expression]) -> Var: 4476 """Build a SQL variable. 4477 4478 Example: 4479 >>> repr(var('x')) 4480 '(VAR this: x)' 4481 4482 >>> repr(var(column('x', table='y'))) 4483 '(VAR this: x)' 4484 4485 Args: 4486 name: The name of the var or an expression who's name will become the var. 4487 4488 Returns: 4489 The new variable node. 4490 """ 4491 if not name: 4492 raise ValueError(f"Cannot convert empty name into var.") 4493 4494 if isinstance(name, Expression): 4495 name = name.name 4496 return Var(this=name)
Build a SQL variable.
Example:
>>> repr(var('x')) '(VAR this: x)'>>> repr(var(column('x', table='y'))) '(VAR this: x)'
Arguments:
- name: The name of the var or an expression who's name will become the var.
Returns:
The new variable node.
4499def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable: 4500 """Build ALTER TABLE... RENAME... expression 4501 4502 Args: 4503 old_name: The old name of the table 4504 new_name: The new name of the table 4505 4506 Returns: 4507 Alter table expression 4508 """ 4509 old_table = to_table(old_name) 4510 new_table = to_table(new_name) 4511 return AlterTable( 4512 this=old_table, 4513 actions=[ 4514 RenameTable(this=new_table), 4515 ], 4516 )
Build ALTER TABLE... RENAME... expression
Arguments:
- old_name: The old name of the table
- new_name: The new name of the table
Returns:
Alter table expression
4519def convert(value) -> Expression: 4520 """Convert a python value into an expression object. 4521 4522 Raises an error if a conversion is not possible. 4523 4524 Args: 4525 value (Any): a python object 4526 4527 Returns: 4528 Expression: the equivalent expression object 4529 """ 4530 if isinstance(value, Expression): 4531 return value 4532 if value is None: 4533 return NULL 4534 if isinstance(value, bool): 4535 return Boolean(this=value) 4536 if isinstance(value, str): 4537 return Literal.string(value) 4538 if isinstance(value, float) and math.isnan(value): 4539 return NULL 4540 if isinstance(value, numbers.Number): 4541 return Literal.number(value) 4542 if isinstance(value, tuple): 4543 return Tuple(expressions=[convert(v) for v in value]) 4544 if isinstance(value, list): 4545 return Array(expressions=[convert(v) for v in value]) 4546 if isinstance(value, dict): 4547 return Map( 4548 keys=[convert(k) for k in value], 4549 values=[convert(v) for v in value.values()], 4550 ) 4551 if isinstance(value, datetime.datetime): 4552 datetime_literal = Literal.string( 4553 (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat() 4554 ) 4555 return TimeStrToTime(this=datetime_literal) 4556 if isinstance(value, datetime.date): 4557 date_literal = Literal.string(value.strftime("%Y-%m-%d")) 4558 return DateStrToDate(this=date_literal) 4559 raise ValueError(f"Cannot convert {value}")
Convert a python value into an expression object.
Raises an error if a conversion is not possible.
Arguments:
- value (Any): a python object
Returns:
Expression: the equivalent expression object
4562def replace_children(expression, fun): 4563 """ 4564 Replace children of an expression with the result of a lambda fun(child) -> exp. 4565 """ 4566 for k, v in expression.args.items(): 4567 is_list_arg = isinstance(v, list) 4568 4569 child_nodes = v if is_list_arg else [v] 4570 new_child_nodes = [] 4571 4572 for cn in child_nodes: 4573 if isinstance(cn, Expression): 4574 for child_node in ensure_collection(fun(cn)): 4575 new_child_nodes.append(child_node) 4576 child_node.parent = expression 4577 child_node.arg_key = k 4578 else: 4579 new_child_nodes.append(cn) 4580 4581 expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
Replace children of an expression with the result of a lambda fun(child) -> exp.
4584def column_table_names(expression): 4585 """ 4586 Return all table names referenced through columns in an expression. 4587 4588 Example: 4589 >>> import sqlglot 4590 >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) 4591 ['c', 'a'] 4592 4593 Args: 4594 expression (sqlglot.Expression): expression to find table names 4595 4596 Returns: 4597 list: A list of unique names 4598 """ 4599 return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
Return all table names referenced through columns in an expression.
Example:
>>> import sqlglot >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) ['c', 'a']
Arguments:
- expression (sqlglot.Expression): expression to find table names
Returns:
list: A list of unique names
4602def table_name(table) -> str: 4603 """Get the full name of a table as a string. 4604 4605 Args: 4606 table (exp.Table | str): table expression node or string. 4607 4608 Examples: 4609 >>> from sqlglot import exp, parse_one 4610 >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 4611 'a.b.c' 4612 4613 Returns: 4614 The table name. 4615 """ 4616 4617 table = maybe_parse(table, into=Table) 4618 4619 if not table: 4620 raise ValueError(f"Cannot parse {table}") 4621 4622 return ".".join( 4623 part 4624 for part in ( 4625 table.text("catalog"), 4626 table.text("db"), 4627 table.name, 4628 ) 4629 if part 4630 )
Get the full name of a table as a string.
Arguments:
- table (exp.Table | str): table expression node or string.
Examples:
>>> from sqlglot import exp, parse_one >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 'a.b.c'
Returns:
The table name.
4633def replace_tables(expression, mapping): 4634 """Replace all tables in expression according to the mapping. 4635 4636 Args: 4637 expression (sqlglot.Expression): expression node to be transformed and replaced. 4638 mapping (Dict[str, str]): mapping of table names. 4639 4640 Examples: 4641 >>> from sqlglot import exp, parse_one 4642 >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 4643 'SELECT * FROM c' 4644 4645 Returns: 4646 The mapped expression. 4647 """ 4648 4649 def _replace_tables(node): 4650 if isinstance(node, Table): 4651 new_name = mapping.get(table_name(node)) 4652 if new_name: 4653 return to_table( 4654 new_name, 4655 **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")}, 4656 ) 4657 return node 4658 4659 return expression.transform(_replace_tables)
Replace all tables in expression according to the mapping.
Arguments:
- expression (sqlglot.Expression): expression node to be transformed and replaced.
- mapping (Dict[str, str]): mapping of table names.
Examples:
>>> from sqlglot import exp, parse_one >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 'SELECT * FROM c'
Returns:
The mapped expression.
4662def replace_placeholders(expression, *args, **kwargs): 4663 """Replace placeholders in an expression. 4664 4665 Args: 4666 expression (sqlglot.Expression): expression node to be transformed and replaced. 4667 args: positional names that will substitute unnamed placeholders in the given order. 4668 kwargs: keyword arguments that will substitute named placeholders. 4669 4670 Examples: 4671 >>> from sqlglot import exp, parse_one 4672 >>> replace_placeholders( 4673 ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" 4674 ... ).sql() 4675 'SELECT * FROM foo WHERE a = b' 4676 4677 Returns: 4678 The mapped expression. 4679 """ 4680 4681 def _replace_placeholders(node, args, **kwargs): 4682 if isinstance(node, Placeholder): 4683 if node.name: 4684 new_name = kwargs.get(node.name) 4685 if new_name: 4686 return to_identifier(new_name) 4687 else: 4688 try: 4689 return to_identifier(next(args)) 4690 except StopIteration: 4691 pass 4692 return node 4693 4694 return expression.transform(_replace_placeholders, iter(args), **kwargs)
Replace placeholders in an expression.
Arguments:
- expression (sqlglot.Expression): expression node to be transformed and replaced.
- args: positional names that will substitute unnamed placeholders in the given order.
- kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one >>> replace_placeholders( ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" ... ).sql() 'SELECT * FROM foo WHERE a = b'
Returns:
The mapped expression.
4697def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression: 4698 """Transforms an expression by expanding all referenced sources into subqueries. 4699 4700 Examples: 4701 >>> from sqlglot import parse_one 4702 >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 4703 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */' 4704 4705 Args: 4706 expression: The expression to expand. 4707 sources: A dictionary of name to Subqueryables. 4708 copy: Whether or not to copy the expression during transformation. Defaults to True. 4709 4710 Returns: 4711 The transformed expression. 4712 """ 4713 4714 def _expand(node: Expression): 4715 if isinstance(node, Table): 4716 name = table_name(node) 4717 source = sources.get(name) 4718 if source: 4719 subquery = source.subquery(node.alias or name) 4720 subquery.comments = [f"source: {name}"] 4721 return subquery 4722 return node 4723 4724 return expression.transform(_expand, copy=copy)
Transforms an expression by expanding all referenced sources into subqueries.
Examples:
>>> from sqlglot import parse_one >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
Arguments:
- expression: The expression to expand.
- sources: A dictionary of name to Subqueryables.
- copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:
The transformed expression.
4727def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func: 4728 """ 4729 Returns a Func expression. 4730 4731 Examples: 4732 >>> func("abs", 5).sql() 4733 'ABS(5)' 4734 4735 >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 4736 'CAST(5 AS DOUBLE)' 4737 4738 Args: 4739 name: the name of the function to build. 4740 args: the args used to instantiate the function of interest. 4741 dialect: the source dialect. 4742 kwargs: the kwargs used to instantiate the function of interest. 4743 4744 Note: 4745 The arguments `args` and `kwargs` are mutually exclusive. 4746 4747 Returns: 4748 An instance of the function of interest, or an anonymous function, if `name` doesn't 4749 correspond to an existing `sqlglot.expressions.Func` class. 4750 """ 4751 if args and kwargs: 4752 raise ValueError("Can't use both args and kwargs to instantiate a function.") 4753 4754 from sqlglot.dialects.dialect import Dialect 4755 4756 args = tuple(convert(arg) for arg in args) 4757 kwargs = {key: convert(value) for key, value in kwargs.items()} 4758 4759 parser = Dialect.get_or_raise(dialect)().parser() 4760 from_args_list = parser.FUNCTIONS.get(name.upper()) 4761 4762 if from_args_list: 4763 function = from_args_list(args) if args else from_args_list.__self__(**kwargs) # type: ignore 4764 else: 4765 kwargs = kwargs or {"expressions": args} 4766 function = Anonymous(this=name, **kwargs) 4767 4768 for error_message in function.error_messages(args): 4769 raise ValueError(error_message) 4770 4771 return function
Returns a Func expression.
Examples:
>>> func("abs", 5).sql() 'ABS(5)'>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 'CAST(5 AS DOUBLE)'
Arguments:
- name: the name of the function to build.
- args: the args used to instantiate the function of interest.
- dialect: the source dialect.
- kwargs: the kwargs used to instantiate the function of interest.
Note:
The arguments
argsandkwargsare mutually exclusive.
Returns:
An instance of the function of interest, or an anonymous function, if
namedoesn't correspond to an existingsqlglot.expressions.Funcclass.
4774def true(): 4775 """ 4776 Returns a true Boolean expression. 4777 """ 4778 return Boolean(this=True)
Returns a true Boolean expression.
4781def false(): 4782 """ 4783 Returns a false Boolean expression. 4784 """ 4785 return Boolean(this=False)
Returns a false Boolean expression.
Returns a Null expression.